List Candidates

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering safety. The description adds that results are sorted most-recently updated first, returns compact summaries with slugs, and that filtered queries should use a different tool, offering useful behavioral context beyond 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 description is three succinct sentences that front-load the main action, state ordering, describe the return format, and point to an alternative. No filler or redundant information.

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 the rich schema and annotations, the description provides sufficient context for an agent to select the tool: it is a read-only list of all candidates, sorted, returning compact summaries, with an explicit redirect to search_candidates for filtered queries. The output schema handles return structure, and parameter descriptions handle limits and sort options.

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?

All 5 parameters have full descriptions in the schema (100% coverage), so the schema carries the documentation burden. The main description does not add parameter-level meaning beyond the schema, though the include_contact_info parameter already includes guidance on PII and response size within the schema itself.

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 uses the specific verb 'Lists' and clearly identifies the resource 'all candidates in the account'. It distinguishes itself from the sibling search_candidates by noting it is unfiltered, and adds value by stating the default sort order and compact summary format.

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 directs users to search_candidates for filtered queries, providing a clear alternative. However, it does not explicitly name get_candidate_details for full detail retrieval, though the mention of 'slug values for candidate detail lookup' implies that workflow.

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