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

Annotations already establish read-only, idempotent, non-destructive and closed-world, but the description adds substantial behavioral detail beyond them: no embedding cost, seeds and their exact copies are excluded from results, result ordering, the 'more' continuation flag, removed_seeds handling, and score comparability only within a single call. Those are exactly the non-obvious traits an agent could not infer from the annotations.

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 core mechanism is front-loaded and the sentences carry dense, load-bearing information about results, pay aggregation and seed removal. It is overlong and mixes retrieval mechanics with downstream reporting instructions ('report it as...', 'say so'), which bloats a single paragraph, but little is truly redundant.

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?

There is no output schema, so the description carries full responsibility for return values, and it delivers: seeds-then-ranked results, per-item score and matched passage instead of a snippet, more flag, stated_pay_among_similar with its n/p25/median/p75 breakdown and explicit reporting caveat, not_matchable/partial, and removed_seeds. For a six-parameter semantic-search tool this is complete enough to call correctly without opening anything else.

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, and the description adds real value on top by stating where the ids must come from and by clarifying filtering semantics (a salary condition drops postings that state no salary; a stated pay floor is basis min; new_grad only for a new graduate). Scope and limit are delegated to the schema with only 'as in search_jobs' cross-references, so the gain is moderate rather than complete.

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 names a specific verb and resource ('find postings like ones the user liked') and immediately explains the mechanism: stored vectors of 1-5 seed postings averaged and compared against every other posting. This makes it unambiguously distinct from sibling tools search_jobs and search_by_meaning, which take text queries rather than seed ids.

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 a concrete when-to-use ('widen a search from a posting the user liked') and enumerates exactly which sibling tools produce valid seed ids (search_jobs, filter_jobs, search_by_meaning, similar_jobs, get_company), plus a pointer to job_search_guide. It stops short of naming when a plain search_by_meaning would be the better pick, so the routing guidance is clear but not exhaustive.

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