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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantive context: only people open to offers who left their profile open to agents, emails and phones are never returned, the tool is free, and per-trust-tier rate limits (50/20, 100/50, 1,000/200, 5,000/1,000 per day). That is real behavioral disclosure beyond the structured hints, though pagination/depth limits live only in 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?

Front-loads purpose and filter surface, then result shape, then eligibility/privacy/limits/next steps — a sensible order. It is dense and run-on in places (the long semicolon chain of filters and the four-tier quota sentence), but nearly every clause carries information an agent needs.

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?

With 22 parameters and no output schema, the description does the heavy lifting: it enumerates the card fields returned (handle, headline, seniority, skills with years, recent jobs, pay expectation, 'why'), states eligibility/privacy restrictions, quotas and next-step tools. Nothing an agent needs to call this correctly is missing.

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 91%, so the schema carries most parameter meaning. The description still adds the cross-parameter rule that one of role/technology/query/company is required and the rest narrow, which is nowhere in the schema (required array is empty), plus framing of what people must have matched ('every one is required' for technology is in schema, but the 'narrow' semantics is description-level).

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?

States a specific verb and resource ('Find people on Alion for a role') and immediately enumerates the eligible populations (engineers, data, product, designers, founders) plus the filter surface. An agent can tell this is a candidate-search tool apart from get_person, check_fit and send_message, which are named in the follow-up workflow.

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?

Gives an explicit invocation constraint ('at least one of role, technology, query or company is required, the rest narrow') and a clear next-step workflow (get_person to read, check_fit before writing, send_message to write). It does not explain when to prefer this over the close siblings match_people or similar_people, so the alternative-selection guidance is incomplete.

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