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

Annotations already cover read-only/idempotent/open-world, but the description adds substantial context they cannot: execution on a Fairquery-hosted Worker, inputs leaving the client, robots.txt and private-IP handling, request caps (6 ATS GETs, <=3 pages), retry/backoff rules, and a session-wide kill switch that surfaces as HOST_BLOCKED in meta.notes rather than failing the call. The confidence semantics (high vs medium for slug_probe) is a behavioral caveat an agent must know to interpret results.

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?

Front-loaded WHAT/WHEN/WHEN NOT/COST structure is excellent and each section earns its place. It is long and has minor redundancy — "does not store" is stated twice, and the Personio/Pinpoint/Gem exclusion is repeated in both WHEN NOT and BEHAVIOR.

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 tool with external network egress, a kill switch, and a heuristic that can return ambiguous results, the definition covers everything an agent needs: cost, request ceiling, what each `via` value means, and how to treat medium-confidence slug hits. The output schema exists, yet the RETURNS note still adds the interpretation guidance the schema can't.

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, but the description goes well beyond the schema's "company name, domain or URL" by explaining that the three forms have materially different behavior: URL parsed offline, domain triggers the careers-page crawl, plain name uses seeds plus slug probes. It also documents the slug-derivation rules (legal suffixes stripped, joined/hyphenated/first-word variants) that determine whether a medium-confidence result appears.

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?

Opens with a specific verb and resource: "Resolve a company name, domain or careers/board URL to its public job board(s) on Greenhouse, Lever or Ashby." The scope (which ATSes, which input forms) is stated up front, so an agent can distinguish it from jobs_get_board and jobs_search_companies 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?

Explicit WHEN (before jobs_get_board when only the company is known) and WHEN NOT sections name the alternative for each case: jobs_search_by_location for role/place queries, jobs_get_board when ats+slug is already known, jobs_search_companies for bulk/history. It also lists hard exclusions (Workday, Workable, Recruitee, Rippling, LinkedIn) and tells the agent not to ask the user for a company first.

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