Home / CCA-F / Tool Design & MCP / Fundamentals — Detail & Examples
DWG 2.1 — DETAIL & EXAMPLES

Fundamentals — Detail & Examples

Part of Tool Design & MCP · overview: domain-2.html
In this page

A before/after schema tightening example, a structured tool-error shape, and a worked case of ambiguous tool choice.

2.1aA tool schema, before and after

The difference between a tool the model uses correctly and one it misuses is almost always in the schema, not the model's capability:

WORKED EXAMPLE · TIGHTENING A VAGUE TOOL
BEFOREA tool named update with a single parameter: data (freeform string).
  1. The model can't tell from the name whether this updates a user, an order, a document, or something else.
  2. The freeform string parameter gives no hint what shape of content is expected — JSON? Plain text? A specific field list?
  3. Any two different callers are likely to format data differently, so the tool's own implementation has to guess how to parse it.
Rewrite:update_order_status(order_id: string, status: enum["pending","shipped","cancelled"], note?: string) — name and parameters now fully constrain what the model can pass.

2.1bA structured error response

A tool that fails should say what happened in a shape the caller (often another part of the same agentic system) can act on, not a bare exception string:

Good vs. bad tool error shape
  • Bad: { error: "failed" } — gives the caller nothing to work with.
  • Good: { error_type: "validation", message: "order_id 4471 not found", retryable: false } — the caller (or coordinator) can immediately tell this isn't worth retrying and needs a different order_id.
  • This is the same failure-type vocabulary (transient / validation / business / permission) used for subagent errors in Domain 5.2 — tool-level and agent-level error design share the same underlying logic.

2.1cWhen tool choice gets ambiguous

If a system has both search_orders and get_order_by_id, and a user asks "what's the status of order 4471?", the model should reliably pick get_order_by_id — but only if the two tools' descriptions clearly stake out non-overlapping territory. If search_orders's description doesn't make clear it's for browsing multiple results rather than looking up one known ID, the model may guess wrong or hedge by calling both.

Tool Design & MCP Overview 2.2 Building MCP Servers →
Claude Certified Architect — Study NotesDWG 2.1