Search Candidates

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

Annotations already declare readOnlyHint and non-destructive behavior, so the bar is lower. The description adds valuable context: results are compact summaries optimized for large result sets and returns slug values for downstream use. No contradictions with 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?

Two sentences, front-loaded with the core purpose, and each phrase earns its place: purpose, large-result-set behavior, owner_id scoping, and slug return. No filler.

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?

Given 23 parameters and an output schema, the description covers the essential mental model: search with owner scoping, get compact summaries, use slugs for details. It does not describe custom_fields or other filter types in prose, but the schema fully covers those, so the description is complete enough.

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 covers all 23 parameters at 100%, so baseline is 3. The description supplements key workflow details: owner_id requires resolving via list_users, and the output is slugs usable with get_candidate_details or app links. This is useful beyond the schema alone.

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 opens with 'Search Recruit CRM candidates and return compact summaries designed for large result sets,' which clearly states the verb, resource, and output style. It distinguishes itself from list_candidates (compact vs. likely full records) and other search_* siblings by the candidate resource.

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 provides concrete guidance: filtering by owner_id and resolving user IDs via list_users, and it suggests get_candidate_details as a follow-up using returned slugs. However, it does not explicitly say when not to use this tool or name direct alternatives like list_candidates for full candidate lists.

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