rt_source_candidates

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

With no annotations given, the description carries the full burden of behavioral disclosure. It explains that the tool searches CV text, that results include whyMatched for validation, that it lists role stages and rejection reasons, and that filters AND together. It even warns about interpretation: 'wrong location' two years ago may not apply now, 'failed the assessment' still does. This is rich, useful behavioral context beyond what schema or annotations would provide.

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 longer than average, but every sentence earns its place. It is front-loaded with the core purpose, then progressively adds query syntax, result interpretation, rejection history caution, and filter combination advice. The structure is clear and easy to scan, and despite the length, it is not verbose—each paragraph introduces new, useful 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 11 parameters, no output schema, and no annotations, this description is remarkably complete. It covers the tool's scope (whole database), search semantics (boolean, CV text), output characteristics (whyMatched, role history), filtering behavior (AND combination, excludeOffer), and provides actionable best practices. It leaves minimal gaps for the agent to infer incorrectly.

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 description coverage is 100%, so baseline is 3. The description adds extra meaning for 'query' by specifying boolean operator support and giving examples, and for 'excludeOffer' by explaining its intended use case. However, it does not add such depth to every parameter, though all are already documented in the schema. This is a good increment over the baseline.

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 by clearly stating 'SEARCH THE WHOLE CANDIDATE DATABASE — every person who ever applied or was added, not just one role.' This distinguishes it from the sibling tool rt_search_candidates (which likely targets a single role). It also labels itself as 'the sourcing tool,' giving it a clear role within the offer lifecycle.

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 provides explicit guidance on when to use it: 'use it to find people already in the ATS before going out to LinkedIn.' It also explains when NOT to use it or how to narrow down: 'excludeOffer keeps people already on a role out of the results, which is what you want when topping one up.' It advises on query syntax and search strategy ('Search for the evidence, not the job title'), and warns about rejection history.

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