Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds the crucial behavioral detail that the output deliberately omits company names, phone numbers, and addresses, instead requiring the agent to link the user to werkstatt_finder_url. It also warns against inventing names or contact data. This is a meaningful transparency beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured with clear headings, short bullets, and an early explanatory section. Every paragraph earns its place: purpose, routing logic, argument details, and output behavior. The tone is dense but not bloated, and the most important information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, 4-parameter lookup tool, the description covers the complete flow: when to call, which arguments to provide, and what to do with the output. It also addresses edge cases like unclear fault and how to present results without fabricating data. The few implicit details (e.g., that plz/ort are mutually required in practice) are strongly implied by 'PLZ ODER ort angeben.'

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 25% of the schema parameters have descriptions, but the description's Args section compensates well. It explains PLZ is a 5-digit German postal code, gives an example, explicitly says 'PLZ ODER ort angeben' (provided the relationship between the two), and documents radius range/default and response_format choices. This is substantially more meaningful than the raw schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific action and resource: 'Findet Claimondo-Partner-Werkstätten im Umkreis einer deutschen Postleitzahl.' It clearly identifies the tool's scope and, through the later routing guidance, explicitly distinguishes it from claimondo_finde_gutachter_termine. This makes the purpose and sibling differentiation immediately clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'WANN DIESES TOOL — und wann NICHT' section gives explicit conditional guidance: use it first for selbstverschuldete Schäden, use claimondo_finde_gutachter_termine first for unverschuldete Schäden, and use claimondo_pruefe_anspruch when the fault is unclear. It names alternatives, provides the ordering of steps, and explains why, so an agent can correctly select and sequence this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.