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

Annotations carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond those annotations: the cost ('Costs 10 Zooq credits'), the failure mode ('surfaces as a 422 mentioning entityId; no credits charged'), the pagination behavior ('Offset-paginated'), the exact-match limitation versus LinkedIn's proximate geocoding, and the still-not-usable parameter set (titles, industries, functions, benefits, commitments). This is genuine additional behavioral disclosure. A small deduction because the vague phrase 'Still id-typed and not yet usable' could be more explicit about whether passing values to those params is simply ignored, but overall credit is substantial.

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?

The description is dense but economically written — the long `locations` detail is justified because that parameter has the most behavioral nuance, being LinkedIn-specific and exact-match. The top sentence states the core function, the middle covers scoping constraints, and the closing line bundles the credit cost and cross-references. The 'see that parameter' and 'see the note on `locations`' cross-references avoid repetition across similar filters. Slight deduction: the cross-reference style requires the agent to hunt through multiple parameter definitions, and the note about unusable filters is slightly terse given how central it is to correct invocation.

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 20-parameter search tool with an output schema, complete documentation is hard, and this description rises to the challenge. It covers: which filters work and which do not, how to source external ids, how pagination works, how result ids are consumed downstream, the cost in credits, and the error behavior with no charge. The output schema covers return values, so it need not explain those. An agent could invoke this tool correctly with high confidence from the description alone, which is the defining test for this dimension.

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 would be 3, but the description goes far beyond the schema's bare property definitions. For `locations` it provides a step-by-step discovery procedure (LinkedIn search box, address-bar geoId extraction), a concrete example, case-sensitivity warning, and an exact-match behavioral caveat. For `titles` it clarifies that the schema's 'Title id(s)' means NOT free text, cross-references the `keyword` parameter, and names the upstream rejection error. For `companies` it explains how to obtain an id from job payloads and names the source tool (companies_jobs). This is exemplary parameter enrichment that meaningfully changes how an agent would use the tool.

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 line 'Job/opportunity search with the full filter set' clearly names the verb (search) and resource (jobs), and is immediately distinguishable from sibling search tools: search_people, search_alumni, search_companies, search_job_changes are all individually named. The description goes further than any sibling by explaining the exact-match location semantics and cross-referencing consuming tools (jobs_details_v2, jobs_similar, etc.), making the tool's identity unmistakable.

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?

The description explicitly distinguishes free-text matching from id-typed filters: 'Use `keyword` for free-text role matching instead' and 'NOT free text: a title like Senior Full Stack Developer is rejected upstream'. It also warns that LinkedIn shows proximate results while this search is exact-match, advising 'Prefer a CITY id over a country id'. The idempotence and read-only safety profile are already covered by the annotations, so the description's job is to route the agent's parameter choices, which it does thoroughly.

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