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

With no annotations provided, the description carries the full burden and largely delivers. It discloses a notable behavioral trait ('Two-call gate') and explains the visibility semantics for shared hiring records. It drops a point because 'two-call gate' is cryptic — the agent isn't told what the two calls are or how confirm factors into them.

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?

Three tightly written sentences with front-loaded purpose and no fluff. Each sentence contributes new information. Slight deduction because 'Accepts a name or an id' restates candidate param detail, and the cryptic 'Two-call gate' fragment could have been replaced with a half-sentence explanation at no length cost.

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?

For a 4-parameter tool with no annotations and no output schema, the description covers a lot: purpose, usage boundaries, a behavioral quirk, and visibility implications. Gaps remain — no return value discussion, no explanation of the two-call flow or when confirm is needed — but the most decision-critical context is present.

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 50%, so the description must compensate for body and confirm. It adds 'Two-call gate' (a hint at confirm's role) and 'Accepts a name or an id' (redundant with the candidate param). Body is never addressed, and confirm's role is only hinted at. Partial compensation, so a 3 is appropriate.

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 leads with a specific verb+resource pair, 'Add a note to a candidate', and immediately carves out scope with 'context that is not a verdict'. The examples (assessment summary, sourcing rationale, call recap) clearly distinguish it from the sibling rt_submit_evaluation, so the agent can differentiate at a glance.

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 gives explicit when-to-use guidance with concrete examples and an exclusion clause ('not a verdict') that points toward when NOT to use it. While it doesn't name the sibling tool (rt_submit_evaluation) directly, the 'not a verdict' contrast plus the visibility default explanation gives clear decision context.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses the destructive CV replacement behavior, the requirement for replaceCv, the two-call confirmation gate, and the post-upload verification expectation: "if it comes back unlinked, say so rather than reporting it as attached."

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 front-loaded with the core purpose, then covers side effects, safety rules, and verification behavior. Every sentence earns its place, and the structure moves from high-level action to specific constraints without redundancy.

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?

For a mutating tool with no annotations and no output schema, the description is impressively complete: it covers the key side effect, required confirmation flow, file-source restriction, and post-verification behavior. It does not detail file-type limits or exact response shapes, but those are not essential for safe invocation.

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?

Even though schema coverage is 80%, the description adds meaningful semantics beyond the schema: it explains asCv's role, replaceCv's side effect of demoting an existing CV, and the confirm parameter via the "preview, then confirm" gate. This goes well above the baseline for high schema coverage.

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?

Opens with a specific verb and resource: "Attach a local file to an existing candidate — a CV, or a summary document." It clearly distinguishes itself from sibling tools like rt_add_note or rt_create_candidate by focusing on file attachment and the CV-vs-plain-attachment distinction.

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?

Provides clear procedural context: attach only files the user named, never substitute files, and use a two-call gate (preview, then confirm). It does not explicitly name alternatives or say when not to use the tool, but the usage boundaries are well implied.

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

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

With no annotations, the description carries full burden and does so effectively. It discloses that this creates a real, visible record affecting reporting, always runs a duplicate check in preview, moves the stage immediately after creation, and reports if that stage change fails. It also warns against inventing details, providing a clear safety profile for a mutation tool.

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 long but exceptionally well structured with clear headings (WHAT YOU NEED, TWO-CALL GATE, etc.) and front-loaded purpose. Every sentence provides actionable information—no filler or repetition. The length is justified by the tool's complexity and the absence of annotations or output schema.

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 12 parameters, no annotations, and no output schema, the description covers all critical operational context: prerequisites, recommended fields, the preview/confirm workflow, duplicate handling, stage behavior, and fallback when the stage move fails. An agent has everything needed to invoke the tool correctly and avoid common pitfalls.

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 high (83%), but the description adds substantial meaning beyond it: 'offer' can be title or ID, 'confirm' false/absent means preview only, 'stage' defaults to 'Sourced' with rationale, and it explains the interplay between attachFile/asCv and the recommended fields. This helps the agent map user intent to parameters accurately.

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 a specific and complete statement: 'Create a candidate in Recruitee/Tellent AND place them on a role, in one call.' This clearly names the resource (candidate), the action (create + place on role), and the composite nature that distinguishes it from single-action siblings like rt_set_stage or rt_attach_file.

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 when-to-use and how-to-use guidance: required vs. recommended fields, asking for missing info before creating, the two-call gate (preview then confirm), when to pass stage 'Applied' vs. default 'Sourced', and handling duplicate candidates. It also explains the composite action's benefit over separate calls, though it doesn't name sibling tools directly.

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

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

No annotations are provided, so the description must reveal behavior. It warns about per-offer salary answers and the need to read the offer id, which is a subtle but critical nuance. It doesn't explicitly state read-only, but a 'get' operation implies that. The extra context about the flat response is valuable.

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 concise sentences: the first lists the returned content, the second flags a caveat. No filler, front-loaded purpose. Excellent structure.

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?

The description covers what is returned and highlights a tricky aspect of the data shape (per-offer answers). It doesn't explain the response envelope, but with no output schema present, the description could mention the return format. Still, it's fairly complete for a single-record GET.

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?

The schema has one required parameter (candidateId) with type number, and the description does not elaborate on it. While the meaning is obvious from context, the description adds no parameter detail, and schema coverage is 0%. A brief mention of what to pass would raise this.

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 explicitly states 'Full record for one candidate' and enumerates the contents (contact details, tags, every placement, application answers). This clearly distinguishes it from sibling tools like rt_get_notes or rt_search_candidates.

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 implies this is the tool to use when a complete single-candidate snapshot is needed)Skip. It doesn't explicitly contrast with alternatives, but the

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

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

With no annotations, the description carries full disclosure responsibility. It reveals the output ordering (newest last), flattening behavior, and critically warns that reviewer attribution is unreliable due to API token ownership, advising to rely on the note field. This goes beyond a simple read operation and provides valuable behavioral context.

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 front-loaded with the main purpose in the first sentence, then adds critical usage warnings in subsequent blocks. It is somewhat verbose with repeated advice about duplication and syncing, but each sentence provides actionable information. The structure is organized and not unnecessarily padded.

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?

For a simple list tool with two parameters and no output schema, the description covers the essential aspects: what data is returned, ordering, and key caveats. It also includes practical usage guidance. The lack of pagination or limit details is a minor gap, but overall it is sufficiently complete for effective use.

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?

The schema describes offerId but leaves candidateId without a description (50% coverage). The tool description mentions 'candidate' but does not elaborate on parameter semantics or constraints. It adds minimal meaning beyond the schema; candidateId is implied as the key but not explicitly explained, so it only partially compensates for the coverage gap.

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 clearly states the tool retrieves all evaluations for a candidate, listing specific fields (rating, note, stage, reviewer, date) and the output format (flattened list, newest last). This is a specific verb+resource combination that distinguishes it from siblings like rt_get_notes (notes only) and rt_submit_evaluation (writing).

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 instructs users to read this before writing an evaluation, implying it should be used before rt_submit_evaluation to avoid duplication. It also advises carrying the evaluation ID when syncing to prevent duplicates. While it doesn't name alternative tools, the context clearly indicates when to use this tool.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that notes are returned 'newest first', which is a behavioral detail. However, it does not disclose whether this operation is read-only or destructive, or if it requires authentication, or if there are any side effects. For a simple 'get' operation, it might be safe to assume it's read-only, but the description doesn't explicitly state that. The lack of annotations means the description should have provided more safety context, but it does add the sorting behavior. Since it does not contradict annotations (none exist) and discloses a behavior, a 3 is reasonable. Adding 'read-only' or 'does not modify' would elevate it.

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 one sentence: 'Notes already on a candidate, newest first.' It is highly concise, front-loaded with the purpose, and includes a key sorting detail. No wasted words. Perfectly sized for a simple tool. This is a 5.

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?

The tool is simple: it retrieves notes for a candidate. With 2 params, no output schema, and no nested objects, the description is almost sufficient. It provides the sorting order. However, it lacks any information about the output format (though no output schema exists), and does not mention whether it returns all notes or if pagination is implied. Also, it doesn't clarify what 'notes' are in this system—are they internal notes? Since there is a sibling 'rt_add_note', it likely are notes added by users. The description could have added a bit more context about the notes' source or content, but given the simplicity, a 3 is appropriate. It gives the essential purpose and sorting, but lacks some depth.

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 0%, so the description must compensate for parameter documentation. It does not mention any parameters in the description: candidateId is required but its semantic is obvious from its name; limit is also self-explanatory as a numeric limit. The description does not explicitly state that candidateId identifies the candidate whose notes are retrieved, but that's implied by the tool name and description. Since there are only 2 parameters and both are fairly clear from their names, the description doesn't need to elaborate much. However, because coverage is 0%, the description could have added a sentence like 'Provide candidateId to fetch notes, and optionally set limit to cap the result count.' That would improve it. Given the simplicity, a 3 is acceptable.

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 states what the tool does: it retrieves notes for a candidate, sorted newest first. It clearly identifies the resource (notes) and the subject (candidate). It does not explicitly distinguish from siblings like rt_add_note or rt_get_candidate, but the verb 'get' and resource 'notes' are clear. Slight ambiguity: 'Notes already on a candidate' implies it's a read operation, but it doesn't explicitly say 'retrieve' or 'list'. However, the meaning is clear enough. Not quite a 5 because it doesn't differentiate from rt_get_evaluations or others that might also be about candidate details, but it's specific to notes.

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 does not provide explicit guidance on when to use this tool vs alternatives. It implies it is for reading notes, but without context on when to choose this over rt_add_note or rt_get_candidate. It lacks any mention of prerequisites, ordering, or alternatives. However, the tool name 'rt_get_notes' and description are self-explanatory enough for a simple read operation. A 3 is appropriate for a description that gives basic context but no explicit when-to-use alternatives.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses that rating values vary by tenant and warns that incorrect guessing can file a wrong verdict, adding meaningful behavioral context. However, it does not explicitly note that the tool is read-only or describe the return structure, which is a minor gap.

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 two sentences, front-loaded with the core purpose, followed by a concise justification. No wasted words; every sentence earns its place.

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?

For a zero-parameter, no-output-schema tool, the description is fully sufficient. It states what it returns, why it's critical to use it before evaluations, and gives an example of tenant-specific differences. It covers the essential context for an agent.

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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific information, but none is needed. It doesn't clutter with unnecessary param talk.

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 clearly states that the tool retrieves the company's configured rating scale. It uses an implicit 'get' verb and specific resource ('rating scale'), distinguishing it from sibling tools like rt_get_stages or rt_get_notes.

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?

Explicitly instructs when to use it: 'Read it BEFORE writing an evaluation.' It also explains why (rating values differ per tenant), giving clear context for selection and timing.

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

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

No annotations are provided, so the description carries the burden. It implies a read operation via 'get' but does not explicitly state it is non-mutating or side-effect-free. The description adds minimal behavioral context beyond the basic retrieval.

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 exceptionally concise—two sentences that front-load the purpose and usage. Every word contributes value, with no redundancy.

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?

For a simple read tool with one parameter and no output schema, the description is sufficiently complete. It explains what is returned (stages with IDs) and why it is needed, covering all necessary context.

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?

The schema already fully describes the parameter ('From rt_list_offers'), and the description adds no additional parameter-level detail. With 100% schema coverage, the description does not need to compensate, so a baseline score of 3 is appropriate.

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 clearly states the tool retrieves pipeline stages for a specific offer, including their IDs. It also explains its role as a prerequisite for evaluations, distinguishing it from sibling tools like rt_set_stage or rt_get_evaluations.

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 explicitly states when this tool is needed ('Needed before writing an evaluation'), providing clear usage context. It does not explicitly mention alternatives or when not to use, but the context sufficiently guides the agent.

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

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

With no annotations, the description carries the full burden. It clearly indicates a read/list operation that returns ids, status, and candidate counts, implying no side effects. It also subtly reveals that the response contains offer ids needed elsewhere, but it does not detail pagination or return envelope.

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, zero filler. The first sentence states purpose and outputs; the second provides navigational guidance. Everything earns its place.

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?

The tool is simple (two optional params, no output schema). The description sufficiently covers what it returns and why it should be used first. It lacks explicit return format details, but given the schema and the description's scope, it is nearly complete.

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?

The input schema already describes both parameters (limit and query) with 100% coverage. The description adds no additional parameter-level nuance, so baseline 3 is appropriate; it does not compensate beyond the schema.

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 'List' and names the resource 'roles (offers) in Recruitee/Tellent' with the exact fields returned (ids, status, candidate counts). It also distinguishes itself as the starting point, making its role clear among sibling tools.

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?

'Start here — every other tool is keyed on an offer id' is explicit guidance on when to use this tool first and why: to obtain offer ids for the other tools. This effectively tells the agent to use this tool before any other tool that requires an offer id.

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

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

No annotations are provided, so the description carries the burden. It discloses the scope (single offer) and the data returned (stage, disqualification, ratings), but does not mention pagination behavior, default limit, or any side effects. Since it's a read operation, the lack of mutation warnings is acceptable, but more detail on output structure would improve transparency.

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 a single, concise sentence that packs essential information: scope, data returned, and differentiation from broader queries. No fluff, front-loaded with the key purpose.

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 tool's simplicity (2 params, no output schema), the description is sufficient. It explains the core functionality and scope. However, it could mention that the output includes a list of candidates and possibly pagination, but the schema covers the limit parameter, so the description is adequate for the tool's complexity.

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% with descriptions for both parameters. The description adds context that the tool is scoped to one offer, which clarifies the offerId parameter's role. The limit parameter is self-explanatory, so the description adds minimal extra value, but the scoping note enhances understanding.

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 clearly states the tool returns candidates for a single offer, including stage, disqualification state, and ratings. It explicitly distinguishes itself from a company-wide database query, which differentiates it from sibling tools like rt_search_candidates or rt_get_candidate.

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 implies usage for retrieving candidates scoped to a specific offer, and the schema notes offerId comes from rt_list_offers, providing a clear prerequisite. However, it does not explicitly state when not to use it or mention alternatives, though the scoping hint helps.

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

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

No annotations are provided, and the description gives minimal behavioral detail. It does not mention whether the operation is read-only, any side effects, return format, pagination, or ordering, leaving the agent uncertain about the tool's effects.

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 a single, concise sentence that is front-loaded with the core action. No unnecessary words or details, making it easy to parse and understand.

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?

The description lacks essential context such as the return structure, whether results are paginated, or any error/edge case behaviors. Without an output schema, the agent cannot anticipate what the tool returns, making the description incomplete for effective use.

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?

The query parameter's semantics are partially clarified by the description ('by name or keyword'), but the limit parameter is not described. The schema only provides type and default, so its meaning (e.g., maximum number of results) is not explicitly stated.

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 clearly states the tool's purpose: to find candidates by name or keyword. It distinguishes itself from sibling tools like get_candidate by indicating a search across the company rather than a specific lookup.

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 implies usage when searching by name or keyword, but does not explicitly contrast with alternatives such as get_candidate or list_candidates. There is no direct guidance on when to prefer this tool over others.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the tool refuses to move disqualified candidates, cannot disqualify anyone, requires a preview-then-confirm two-call gate, and verifies the move by re-reading the candidate afterward. This is rich behavioral context beyond any structured field.

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 action, then systematically covers prerequisites, mirroring caveats, non-goals, and the confirmation flow. There is no redundancy or 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 the tool's mutation risk, the absence of annotations, and no output schema, the description is remarkably complete. It covers prerequisites, failure behavior, safety constraints, confirmation requirements, and post-move verification. It leaves little ambiguity for an agent deciding whether and how to invoke the tool.

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 75%, with the `confirm` parameter lacking a description. The description compensates by explaining the two-call gate ('preview, then confirm'), which gives meaning to `confirm`. It also clarifies stage-name behavior ('an unknown name is refused and the real ones are listed back'), adding value beyond the schema's basic parameter descriptions.

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 a specific verb+resource: 'Move an existing candidate into another pipeline stage on ONE of their roles.' It clearly distinguishes itself from sibling tools like rt_get_stages (read-only stages) and explicitly disclaims rejection functionality, making its scope unmistakable.

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 gives explicit when-to-use guidance: advance a candidate or mirror an external move. It also provides alternatives and exclusions: call rt_get_stages first if stage names are unknown, ask which stage is meant when mirroring across systems, and never use as a rejection tool. This is exemplary usage guidance.

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

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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does so excellently: it reveals that the tool operates by name, refuses ambiguous matches to avoid mis-filing, automatically determines the stage, requires a two-call gate with explicit confirmation, and files in the token owner's name (with practical implications). It also notes that structured questionnaires are not supported, which is critical behavioral context. No contradictions.

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 verbose but highly dense with critical usage constraints. It uses all-caps headings for key points, making it scannable despite length. However, some repetition exists (e.g., the two-call gate is mentioned multiple times, and the 'IT IS FILED IN THE TOKEN OWNER'S NAME' section is extensive). It could be more concise without losing essential details, but the structure aids comprehension.

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 tool's high complexity (6 parameters, critical safety implications, no output schema or annotations), the description is remarkably complete. It covers the purpose, usage criteria, behavioral constraints, parameter uses, and edge cases (ambiguous names, unsupported questionnaires). The lack of an output schema is compensated by explaining the two-call preview/write flow, making the behavior fully predictable.

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?

The schema covers all parameters descriptively (candidate, offer, rating, ratingNote, stage, confirm), but the description goes further by clarifying the meaning of 'offer' (role title or id, not an offer object) and 'candidate' (full name, not id). It also emphasizes that ratingNote should contain auditable reasoning. Although it doesn't detail every parameter's syntax, the high schema coverage (100%) reduces the need. The description adds value by explaining the two-call gate and the confirmation semantics.

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 clearly states the tool writes an evaluation (rating + note) onto a candidate for a role, targeting the 'Evaluation' tab. It explicitly distinguishes it from sibling tools like rt_get_evaluations (which reads) and rt_add_note (which likely writes a generic note, not an evaluation). The purpose is specific and unambiguous.

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 extensive usage guidance: it explains when to use this tool (to file an evaluation), when not to (never for conversations the token owner didn't have), and explicitly directs to call rt_get_rating_scale if unsure about ratings. It also names sibling tools (rt_get_rating_scale) and clarifies the two-call gate pattern, leaving no ambiguity on when to invoke this tool.

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