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

Annotations only declare read-only/idempotent/closed-world; the description adds substantial behavioral context beyond them: mixed units (annual vs monthly gross euros) that must never be combined, absence of true min/max/percentiles in the JobJump aggregate, nationwide-only coverage, and the fact that search_region is accepted but not applied. It also scopes out tax/net advice and personal data.

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?

Four dense paragraphs, all front-loaded with purpose before caveats, and nearly every sentence carries a real constraint. Slight redundancy: the search_region no-op and the job_title normalisation are stated in both the description and the schema.

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?

Given an output schema and full annotation coverage, the description supplies exactly the interpretive layer they cannot: how to read series_id/provenance, which units are incomparable, and what the tool does not cover. Nothing needed to call or interpret it correctly is missing.

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 coverage is 100%, so the baseline is 3; the description earns above that by explaining that search_region changes no figure and by stating that figures are per-series with their own unit/statistic/vintage keyed by series_id. Some overlap with schema text (job_title in the user's own words, gendered-form normalisation) is redundant rather than additive.

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 ('look up what an occupation pays in Germany') plus the two data sources combined. It also explicitly distinguishes itself from evaluate_salary_offer and calculate_net_salary, so an agent can route correctly without opening schemas.

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?

Names the triggering question ('what a role pays or how pay differs by seniority') and names two alternatives with the conditions that select them ('to judge a specific offer, use evaluate_salary_offer'; 'For net pay, call calculate_net_salary'). It also pre-empts a false-negative read by noting that a missing occupation is normal, not an error.

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