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

Annotations only declare read-only and closed-world; the description adds genuinely new behavior: the 'building' status with retry_after_seconds for un-analysed postings, and a 'not_held' status with fallback market_now and a report link. With no output schema, these response-state disclosures carry real weight, though expiry/freshness of cached results is unstated.

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?

Roughly the first two lines are an occupation catalogue ('healthcare, finance, IT, engineering... retail and food') that does no work for tool selection and delays the actual point. The remaining content is dense but run-on, with multiple ideas packed into single sentences.

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 six-parameter, no-output-schema tool it covers the essentials: how to identify the posting, what comes back for free, what the paid sibling adds, and the two degraded response statuses. What's missing is handling of the zero-required-parameter case and precedence among identification inputs.

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 50% (city, title, employer undocumented), but the description compensates by spelling out the three identification paths — careers-site URL, VeritaHire job id, or employer+title+city/state — which is meaning the schema alone doesn't convey. It stops short of saying which combination takes precedence when several are supplied.

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 description states a concrete resource (the posted pay range for a role within 25 miles, employer count) and distinguishes itself from the named sibling request_competitive_hiring_report, which holds the competitor-by-name detail. The core purpose is clear, though it is buried behind a 20-occupation enumeration that obscures the verb.

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 explicitly partitions free data (pay range, employer count, time to close) from what requires the request_competitive_hiring_report call, which is a real when-to-use/when-to-use-the-other statement. It gives no guidance for choosing against hiring_market, hiring_signals, or is_job_still_open, so the routing is only partial.

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