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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds the useful behavioral note that results are IDs plus canonical citation URLs, which steers the agent to fetch, but says nothing about matching behavior (title vs. full text), result caps, or ranking.

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?

Three short sentences, no padding, with the core purpose front-loaded and the disambiguation and return-shape notes following in priority order. Every sentence changes how an agent would call the tool.

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?

A one-parameter read-only tool with an output schema and rich annotations needs little more than this, and the description covers purpose, the query semantics trap, sibling routing, and the return shape. It falls short of 5 only because it omits how keyword matching works and what happens with multi-word queries.

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?

Schema description coverage is 0%, so the description carries the burden and does so meaningfully: it defines query as keyword text rather than a natural-language filter expression, which is exactly the misunderstanding that would cause a bad call. It does not mention the 1–300 character constraint or how multiple keywords combine, leaving a small gap.

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?

States a specific verb and resource ('Search German physician job adverts by keywords') and immediately bounds the scope of the tool versus the sibling that handles filters. The agent can distinguish this from suche_arztstellen and from the lese_* siblings without opening any schema.

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?

Explicitly narrows usage by warning that 'query is keyword text, not a natural-language filter parser' and routes location/role/exclusion/pagination needs to suche_arztstellen. It lacks an explicit positive 'use this when you only have free-text terms' clause and says nothing about the lese_* or fetch siblings' place in the workflow beyond 'Returns IDs for fetch', but the when-not guidance is clear.

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