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

Beyond the annotations (which already declare read-only, idempotent, closed-world), the description discloses normalization rules, result cardinalities (up to 30 siblings, up to 5 aliases), the fact that failure is a success with `resolved: null`, and which content is deliberately omitted (no salary figures, profile excludes pay sentences and FAQs). That is substantive behavioral context an agent could not infer from the schema.

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?

Purpose is front-loaded and the paragraph on sibling-tool routing is genuinely load-bearing. Some sentences duplicate the schema's `include` descriptions and the output schema's field list, which is minor redundancy in an otherwise well-organized text.

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?

An agent knows when to pick this tool, what to pass, what the result shape contains, what happens on no match, and where to go for pay or postings. With an output schema present, the description need not explain return values, yet the brief naming of returned fields aids selection without bloating.

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 nevertheless adds intent-level guidance — 'ask only for what the user needs', the note that both sections are general editorial content, and the explicit reminder that the profile excludes pay. It largely restates what the schema already says for `include`, so it does not go far beyond the baseline.

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 names a specific verb pair (map, optionally describe) and a specific resource (job title → JobJump occupation), including the normalization step. It is clearly distinguishable from siblings such as search_jobs, get_salary_benchmark and get_tariff_pay, which are explicitly named as separate concerns.

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?

It gives concrete triggering conditions (unusual, colloquial, English or gendered wording; questions about what the job involves or how to write a CV) and explicit exclusions routed to alternatives ('call get_salary_benchmark or search_jobs', 'get_tariff_pay for public-sector pay'). It also covers the failure path, telling the agent to ask for another wording when `resolved` is null.

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