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

Without annotations, the description carries the full burden, but it only adds 'Write operation,' which is already implied by the verb 'Add.' It doesn't disclose permissions, reversibility, or other side effects beyond saying the note appears in the activity feed. This is insufficient 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 brief and front-loaded, with the core action in the first sentence. The example utterances and prerequisite are useful and non-redundant, though 'Write operation' is somewhat redundant given the action.

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 presence of an output schema and the simplicity of the tool, the description covers the essential context: what it does, when users would invoke it, and how to get the required ID. It could benefit from noting the visibility options, but those are in the schema.

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 3 parameters with descriptions, so baseline is 3. The description adds value by explaining how to locate candidate_id via search_candidates_by_name, which goes beyond the schema. Body and visibility are adequately documented in 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 clearly identifies the action ('Add a text note') and the target resource ('candidate's activity feed'), distinguishing it from sibling tools like add_tag_to_candidate by specifying it's a text note. The 'Write operation' phrase reinforces the mutation intent.

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 user utterances ('add a note to Sarah's profile') that signal when to use this tool, and points to search_candidates_by_name as the way to obtain the required candidate_id. However, it doesn't explicitly state when not to use it or mention alternative tools like add_tag_to_candidate.

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. It explicitly labels the operation as 'Write operation', which is useful, and implies tags must already exist (via 'list_tags → match by name'). However, it does not disclose idempotency, behavior on duplicate tags, permissions required, or error conditions, leaving notable gaps in behavioral 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 compact and front-loaded: a one-sentence purpose, followed by terse usage examples, ID resolution tips, and a single alternative tool mention. Every sentence earns its place 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 two-parameter write operation with an output schema present, the description covers purpose, usage, ID resolution, and alternatives. It does not explain edge cases like duplicate tags or required permissions, but these are not essential for basic invocation. The explicit 'Write operation' flag partially compensates for missing annotations.

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 candidate_id and tag_id. The description adds value beyond the schema by recommending how to find each ID (search_candidates_by_name, list_tags → match by name) and providing real-world usage phrasing that helps the agent map user intent to parameters.

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 'Apply a tag to a candidate' with a specific verb and resource. It also distinguishes itself from the sibling tool bulk_tag by explicitly directing bulk tagging elsewhere, and the name itself differentiates from add_note_to_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 provides explicit when-to-use guidance with natural language examples ('tag Sarah as referred'), how to resolve candidate_id and tag_id via search_candidates_by_name and list_tags, and an explicit exclusion for bulk tagging ('use bulk_tag instead'). This fully covers usage context and 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?

With no annotations provided, the description carries the full burden. It discloses that this is a write operation, explains default behavior when stage IDs are omitted ('advance to the natural next stage'), and implies a state change. However, it does not mention edge cases like what happens if the candidate is already at the final stage, or any permission/authorization requirements, which would ideally be included for a mutation tool with no annotation support.

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 well-structured: a clear opening statement, then usage examples, a workflow hint, and explicit alternative tools. Every sentence adds value and the length is appropriate for the tool's complexity. It is front-loaded with the core 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?

The tool has an output schema (not shown), so return values need not be described. The description provides the core purpose, usage context, parameter guidance, and alternatives. It is adequate for a single-application advancement but could be slightly more complete with edge-case behavior. Overall, it is a well-rounded description.

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 provides 100% description coverage. The tool description adds meaningful context beyond the schema: it explains how to get the application_id via a search chain, and clarifies that to_stage_id is optional and defaults to the next natural stage. This helps the agent understand parameter intent beyond the basic 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 clearly states the action: 'Move a candidate forward one stage in their job pipeline.' This is a specific verb+resource combination that distinguishes it from sibling tools like reject_application or bulk_advance. The 'Write operation' note further clarifies its nature.

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 explicit usage guidance: includes example user phrases, a step-by-step workflow for obtaining the application_id, and clearly names alternatives ('To skip stages, use move_application_same_job. For bulk advancing, use bulk_advance.'). This goes beyond minimal guidance to actually direct the agent on when to use this tool vs 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?

With no annotations, the description takes on full responsibility. It clearly states 'Write operation — rate-limited' and 'Processes sequentially with rate-limit delays,' which are critical behavioral traits. It doesn't mention permission requirements or partial failure behavior, but the key operational constraints are disclosed.

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 compact and front-loaded: purpose, critical warning, practical usage, and optional parameter logic—all in three sentences with no wasted words. Every sentence adds value.

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 complexity (bulk operation, optional filtering, rate limits) and the presence of an output schema, the description adequately covers what an agent needs: how to identify target applications, when to use from_stage_id, and the sequential/rate-limited execution. It could mention error handling or what happens if some applications are invalid, but that's a minor gap given the schema's output coverage.

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%, but the description adds significant meaning: it tells users to get application_ids from pipeline_summary or list_applications, and explains that from_stage_id should be matched by name via list_job_stages_for_job. This is practical workflow knowledge beyond the schema's field 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 'Advance multiple applications to the next stage,' a specific verb+resource combination. The word 'multiple' distinguishes it from the sibling tool advance_application, which handles single applications.

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 clear guidance on when to use: includes a natural-language trigger ('move everyone past phone screen forward'), tells users where to get application_ids (pipeline_summary or list_applications), and how to optionally filter by stage using list_job_stages_for_job. It doesn't explicitly say 'use advance_application for a single application,' but the bulk semantics make it clear.

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 discloses that this is a 'Write operation — rate-limited' and that it 'Processes sequentially with rate-limit delays.' This adds useful behavioral context beyond the schema, though it does not mention reversibility or other side effects like email sending (which is parameterized).

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 compact paragraph with a clear front-loaded first sentence. The user example and workflow are relevant, but the text is somewhat dense and could be structured with bullets or shorthand. Still, every sentence adds value.

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 complexity (batch write operation, 3 params, output schema), the description is fairly complete. It covers the use case, prerequisites, and rate-limit behavior. Minor omissions like maximum batch size or error handling are not described, but the output schema likely sufficient.

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 describes all parameters (100% coverage), so the baseline is 3. The description adds extra semantics by describing how to obtain application_ids via stale_applications and how to match rejection_reason_id by name using list_rejection_reasons, which enriches the parameter guidance.

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 'Reject multiple applications in one call,' which is a specific verb (reject), resource (applications), and scope (multiple in one call). This clearly distinguishes it from the sibling reject_application, which handles a single application.

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 a concrete usage example: 'First use stale_applications to identify the targets, then pass their application_ids here.' It also advises matching rejection_reason_id via list_rejection_reasons, giving a clear workflow. However, it does not explicitly state when not to use this tool (e.g., for a single rejection), so it lacks full exclusion 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, the description carries the full burden. It discloses that it is a write operation, is rate-limited, processes sequentially with delays, and auto-creates tags if new. This is strong behavioral disclosure beyond the schema, though it does not cover error handling or edge cases.

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 sentences, front-loaded with the core action, then adds a practical usage example and rate-limit behavior. No wasted words; every sentence contributes useful context.

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 2-parameter tool with an output schema, the description covers the essential safety profile (write, rate-limited), usage context, and parameter sources. It could be more explicit about alternatives, but overall it is complete enough for an agent to select and invoke correctly.

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% and already explains both parameters, including the auto-creation of tags. The description adds minimal new semantic value by mentioning 'from search or pipeline tools,' but this largely duplicates the schema's 'get from list_candidates or search.' Baseline 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 opens with 'Tag multiple candidates in one call,' which clearly states the verb, resource, and batch scope. It distinguishes itself from single-candidate tagging siblings like add_tag_to_candidate by emphasizing 'multiple' and 'bulk' behavior.

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 concrete usage context: 'Users say "tag all the candidates from the hiring event"' and instructs to pass candidate_ids from search or pipeline tools. It implicitly differentiates from single-tag tools but does not explicitly state when not to use it or name 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 full burden. It explicitly states 'Read-only', discloses that results are sorted by urgency, and clarifies that it returns both stale applications and interviews missing scorecards. This is solid behavioral disclosure, though it does not mention pagination or rate limits.

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 compact and front-loaded, leading with the core purpose and read-only nature, then providing user-intent examples and parameter guidance. Every sentence adds value without unnecessary verbosity.

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-only query tool with two optional parameters, an output schema, and clear sibling alternatives, the description covers purpose, usage, parameter behavior, and return contents. It could mention pagination or sorting direction more explicitly, but it is largely complete 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% and the parameter descriptions already explain job_id ('Filter to one job — list_jobs → match by name') and stale_days ('Days without activity to flag as stale'). The tool description adds a little context ('omit for all active applications') but mostly reinforces what the schema already conveys, so the baseline 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 uses a specific verb ('find') and resource ('candidates that need attention'), and clearly defines the scope as stale applications and missing scorecards. It distinguishes itself from the sibling 'stale_applications' by adding the scorecard component and the attention/urgency framing.

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 clear usage context with example user queries ('what needs my attention?', 'who's been sitting too long?') and explains when to pass job_id versus omit it. It does not explicitly name exclusions or alternatives, but the guidance is sufficient for a straightforward read-only query 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?

With no annotations, the description carries the full burden. It does disclose that the operation is read-only, which is a key behavioral trait. However, it does not mention potential error conditions, rate limits, or how the content is returned (binary vs base64), though the output schema likely covers return format.

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 short sentences that convey purpose, read-only nature, and usage guidance. No filler, front-loaded with the main action, and 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 simple one-parameter download tool with an output schema, the description fully covers the when and where. The usage context is clear, the parameter is well-defined, and no ambiguity remains about intended 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 fully describes the required 'url' parameter (100% coverage), meeting the baseline. The description adds value by contextualizing the parameter's source (from candidate attachments or application data) and giving a concrete example of where to obtain it, going slightly 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 states a specific verb ('Download') and resource ('content from a Greenhouse attachment URL'), making the tool's function immediately clear. It also implicitly distinguishes itself from siblings by focusing specifically on attachment URLs, unlike read_candidate_resume or other resume-specific 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?

The description gives explicit guidance on when to use the tool ('Use when you have a specific attachment URL from a candidate or application record') and provides a concrete example (get_candidate's attachments array). It does not name alternative tools or exclude cases, but the context is strong.

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. It states 'Read-only,' which is a key behavioral trait, and describes the return format (grouped by job with candidate names, sources, stages, screening answers). It does not mention potential side effects or API cost details beyond the schema, but the read-only declaration and output shape provide solid 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?

Three sentences: a front-loaded summary, a user-quote example, and a return-format explanation. Every sentence earns its place, with zero fluff. The structure is clear and immediately scannable.

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 presence of an output schema and the read-only nature, the description covers the essentials: purpose, usage example, parameter handling, and return shape. It adequately differentiates from sibling tools and provides enough context for an agent to select and invoke it correctly.

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 the baseline is 3. The description repeats the schema guidance for 'since' and 'job_id' (e.g., 'list_jobs → match by name') but adds no new parameter semantics beyond what the schema already provides. It does not mention 'status' or 'include_candidate_details' defaults, relying on 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 a specific verb+resource+scope: 'Applications since a date, grouped by job — the daily digest.' It clearly distinguishes from siblings like list_applications by emphasizing grouping and the daily digest use case, and it explicitly mentions returning candidate names, sources, stages, and screening answers.

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 a clear use case: 'Users say "what new applications came in since yesterday?"' and explains how to filter by job via list_jobs. It does not explicitly name alternatives or state when not to use it, but the context makes the primary scenario obvious. It lacks direct exclusions, so it falls short of a 5.

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 explicitly states 'Read-only' and describes the return content (notes, emails, stage changes) in chronological order, which are important behavioral traits. It does not cover every possible edge case (e.g., pagination), but for a simple read-only timeline it is sufficiently transparent.

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 concise and well-structured: a clear one-line purpose, a read-only declaration, example phrasing, a prerequisite link, and a summary of the return content. Every sentence contributes meaning 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 tool with one parameter and an output schema, the description covers purpose, behavior, usage context, and parameter acquisition. The output schema handles return values, so no further detail is needed. It is complete for an agent to select and invoke correctly.

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 provides 100% coverage for candidate_id with 'Greenhouse candidate ID'. The description adds value by pointing to search_candidates_by_name as a way to obtain the candidate_id, which is a useful cross-reference 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 clearly states the tool 'Get a candidate's activity timeline' with a specific verb and resource, and differentiates from siblings like get_candidate by focusing on timeline events (notes, emails, stage changes). It 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 clear usage context with example user phrases ('show me Sarah's history') and a prerequisite (use search_candidates_by_name to find candidate_id). However, it does not explicitly mention alternatives or when not to use this tool, so it misses the 'when-not' aspect.

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. It explicitly states 'Read-only' (a safety trait) and implies this tool does not provide the complete screening package (resume, location) by directing to screen_candidate. However, it does not mention permissions, error behavior, or other potential side effects, so it falls short of a 5.

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 sentences, each earning its place: purpose, ID discovery workaround, and alternative tool recommendation. It is front-loaded with the main purpose and contains no fluff.

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 single-get tool with an output schema, the description is complete. It covers the core action, provides a path to obtain the required ID, and points to a richer alternative. Return value details are handled by the output schema, so no further explanation is needed.

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% and the parameter description already states 'Greenhouse application ID'. The description adds little beyond the word 'ID' in 'Get a single application by ID', which is redundant. Baseline 3 is appropriate since the schema does the heavy lifting.

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 'Get a single application by ID. Read-only.' which is a specific verb+resource. It also distinguishes itself from sibling tools like list_applications and screen_candidate by emphasizing the single-record nature and pointing to screen_candidate for a broader screening package.

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 guidance: it acknowledges users rarely know IDs, provides a discovery workflow (search_candidates_by_name → get_candidate → applications array), and recommends screen_candidate for full screening. This goes beyond mere context and establishes clear when-to-use and when-not-to-use conditions.

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 explicitly states 'Read-only,' which is a critical safety signal. It also details what is returned (name, contact info, all applications, tags, custom fields, attachments), adding value beyond the schema. It does not mention error/not-found behavior, but for a read-only lookup with a single ID parameter, the coverage is strong.

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 concise sentences front-loaded with purpose, followed by return contents and usage alternatives. Every sentence earns its place, and there is no fluff or repetition of schema details. It is highly scannable and appropriately sized.

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 a central lookup with an output schema (context signal indicates true), so the description doesn't need to explain return structure. It covers purpose, read-only nature, key return contents, and relationship to sibling tools. This is complete for an agent to select and invoke the tool correctly.

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 has 100% coverage with a description for candidate_id ('Greenhouse candidate ID'). The description only says 'by ID,' which adds little beyond the schema. No additional semantics about format, requiredness, or constraints are provided, so the baseline 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 opens with a specific verb and resource: 'Get a candidate's full profile by ID.' It clearly distinguishes itself from siblings by stating it is the 'central lookup' and explicitly names alternatives like search_candidates_by_name and screen_candidate. This leaves no ambiguity about what the tool does.

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 usage guidance: it says this is the central lookup after resolving a name via search_candidates_by_name, and directs users to screen_candidate when they need a screening package with resume and location. This offers clear when-to-use and when-not-to-use context, differentiating it from similar candidate-focused tools.

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 explicitly states 'Read-only' and enumerates the returned fields (name, status, departments, offices, hiring team, custom fields). However, it does not disclose error behavior (e.g., job not found) or any authorization requirements, leaving some transparency 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 compact: one purpose sentence, one return-fields sentence, and a structured enumeration of alternative tools. Every sentence earns its place, with no redundancy or filler, and key information is front-loaded.

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 get-by-ID tool with one required parameter and an output schema, the description covers the purpose, usage, expected return content, and alternatives. The presence of an output schema obviates the need to describe return types in detail, and nothing essential is missing 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?

The schema provides a terse description 'Greenhouse job ID' (100% coverage), so the baseline is 3. The description adds significant value by instructing 'Use list_jobs to find the job_id by name first,' which tells the agent how to source a valid parameter value beyond what the schema offers. This elevates the score to 4.

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 function: 'Get full details for a job by ID' — a specific verb, resource, and scope. It distinguishes from sibling tools by explicitly noting the public listing (list_job_posts_for_job) and pipeline stages (list_job_stages_for_job) as separate concerns, making the purpose 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 explicit when-to-use guidance: 'Use list_jobs to find the job_id by name first' and names specific alternatives for other related tasks. It tells the agent exactly when to use this tool versus siblings, satisfying the dimension fully.

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 states 'Read-only' and describes the return content (ratings, attribute scores, recommendation), which adds valuable context about side-effect safety and what the caller can expect. While it doesn't cover error cases or permissions, for a simple read operation this is sufficient.

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 short sentences, front-loaded with the primary purpose, then returning content, and finally a usage tip. Every sentence earns its place with no repetition or filler. It is concise and well-structured.

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 single-parameter read-only tool with an output schema, this description is complete. It states what it does, what it returns, and how to find the required ID. There is no missing context for an agent to invoke it correctly, and the sibling differentiation eliminates ambiguity.

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 documents the only parameter with 100% coverage, including the instruction to get the ID from list_scorecards_for_application. The description repeats this guidance but adds minimal new meaning for the parameter itself. Given the high schema coverage, 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's purpose: 'Get a single scorecard by ID' with a specific verb and resource. It also differentiates from the sibling list_scorecards_for_application by noting that the latter is for finding IDs. This makes the tool's scope immediately clear.

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 tells the agent when to use this tool vs the alternative: 'To find scorecard IDs: list_scorecards_for_application.' It also marks the operation as 'Read-only,' giving clear context on safe usage. This is direct, actionable 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 provided, the description carries the full burden and it explicitly states 'Read-only,' which is the key behavioral trait for safe invocation. It does not discuss pagination or cursor behavior, but those are fully documented in the input schema and no destructive behavior is implied.

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 and read-only note, then provides compact trigger examples, ID-derivation steps, and sibling routing. Every line earns its place and there is 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?

For a 9-parameter filterable list tool with an output schema, the description covers purpose, safety, natural-language triggers, parameter derivation, and alternative tools. The remaining details (ISO formats, pagination flags) are already fully documented in the input schema.

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%, so baseline is 3, and the description adds value by explaining how to obtain the foreign key values: list_jobs to find job_id and search_candidates_by_name to find candidate_id. This is workflow knowledge not present in 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 a specific verb and resource — 'List applications with optional filters' — and immediately marks it read-only. It also distinguishes itself from sibling tools by naming pipeline_summary, stale_applications, and candidates_needing_action as different views.

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 gives concrete trigger phrases ('show me applications for [job name]', 'what came in this week') and explicit routing: use list_jobs/search_candidates_by_name to get IDs, use pipeline_summary for stage-grouped views, and use stale_applications/candidates_needing_action for stale candidates. This is clear when-to-use vs alternatives 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 provided, the description carries the safety burden, and it explicitly declares 'Read-only.' It also signals bulk-operation behavior, implying larger result sets. It doesn't cover rate limits or auth, but no side-effect ambiguity remains.

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 short sentences, front-loaded with core purpose and safety declaration. The use-case guidance is placed immediately after, and 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?

The tool has no required parameters, an output schema, and a clear role among siblings. The description supplies essential selection and safety context, while the schema handles parameter and return details, so nothing critical 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?

All 9 parameters are already documented in the input schema with 100% coverage, so the baseline applies. The description's references to date-range queries, specific IDs, and pagination map to those parameters without adding new semantic detail beyond what the schema provides.

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?

Description opens with 'List candidates with optional filters' — a specific verb, resource, and filter concept. It then distinguishes itself from search_candidates_by_name and search_candidates_by_email, making the tool's role immediately clear.

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 states when to avoid this tool ('For finding a specific person') and names the faster, simpler alternatives. It also enumerates the intended use cases: date-range queries, fetching by specific IDs, and paginating through the full database.

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 supplied, the description carries the safety burden and it does so by explicitly labeling the tool 'Read-only.' It also states the scope ('all jobs with optional filters') and the job-ID-resolution behavior. It does not describe pagination side effects in prose, but the input schema already documents cursor and paginate behavior.

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?

Four short sentences, front-loaded with the core action and read-only nature, then the use case, filters, and alternative. Every sentence contributes information; 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?

For an 8-parameter filtered list tool, the description covers what it does, when to use it, how to find job IDs, what filters matter, and which sibling covers pipeline views. Pagination and return-value details live in the schema and output schema, so nothing essential 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 100%, so the baseline is 3. The description adds meaning beyond the schema by naming the primary job-title-to-ID use case and pointing to list_departments and list_offices as sources for filter values, plus enumerating the status choices. This is useful parameter guidance not fully present in 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?

Description opens with a specific verb and resource ('List all jobs') and immediately states a clear retrieval use case: resolving job titles to job IDs. It also points to a sibling alternative (pipeline_summary), so an agent can distinguish this tool from nearby list/detail 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?

The description gives explicit when-to-use guidance: whenever a user mentions a job by name, use list_jobs to find the matching job_id. It also provides a when-not-to-use signal by directing pipeline views to pipeline_summary instead.

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 of behavioral disclosure. It explicitly states 'Read-only', which is a critical safety trait. It also mentions 'in order' implying sorted output. However, it does not describe return format, error cases, or pagination, but for a simple read-only list tool this is adequate.

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 sentences long and front-loads the core purpose before adding usage context. Every sentence earns its place, with 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 tool's low complexity (single parameter, no nested objects) and the presence of an output schema, the description covers all essential aspects: purpose, ordering, read-only nature, and the workflow to resolve stage names to IDs. It is complete for its intended 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 already provides 100% coverage with 'Greenhouse job ID'. The description adds extra value by explaining how to obtain the job_id via 'list_jobs → match by name', enhancing the semantic understanding beyond the schema's bare description.

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 verb ('List'), resource ('pipeline stages for a specific job'), and scope ('in order'). It also distinguishes the tool as 'the primary tool for resolving stage names to stage IDs', setting it apart from sibling tools like list_jobs or pipeline_summary.

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: 'When a user says "move to the onsite stage," use this to find the stage_id.' It also provides a concrete prerequisite workflow: 'To find the job_id first: list_jobs → match by name.' This clearly instructs the agent on invocation 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 provided, the description carries the disclosure burden. It explicitly says 'Read-only,' which is a meaningful behavioral guarantee, and adds that it resolves names to IDs. It does not describe caching or pagination behavior, but the input schema already documents force_refresh and cursor semantics, so the added value is solid.

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 short, front-loaded with the core purpose and read-only nature, and then gives a concrete usage example. Every sentence adds value; there is no fluff or repetition.

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/lookup tool with a full output schema and 100% parameter coverage, the description is complete. It defines the tool's job, safety profile, and how it fits into the rejection workflow, which is enough for an agent to select and invoke it correctly.

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 the baseline is 3. The description adds no extra parameter-level detail, but the schema already thoroughly explains cursor, per_page, and force_refresh, so no significant gap exists.

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 action ('List all rejection reasons'), the resource, and a clear purpose ('Resolves rejection reason names to IDs'). This distinguishes it from the sibling list tools and marks it as a lookup/ID-resolution tool rather than a general application or candidate list.

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 an explicit usage scenario: when a user mentions a rejection reason by name, use this tool to find the ID, then pass it to reject_application or bulk_reject. This tells the agent exactly when and how to use the tool in a workflow.

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 explicitly states 'Read-only' and discloses the return content (interviewer ratings and overall recommendation). This meaningfully conveys the behavioral profile, even though it omits details like error handling or permissions.

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 compact: a single purpose sentence, a 'Read-only' label, a lookup hint, and a return summary. It is front-loaded with the main action and every sentence earns its place—no redundant or filler content.

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 (one parameter, existing output schema), the description is complete: it states the purpose, how to obtain the required ID, and what the response contains. It adequately covers all necessary contextual information for an AI agent to use it effectively.

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% (application_id described as 'Greenhouse application ID'), so the baseline is 3. The description adds value by explaining how to look up the application_id through a context chain, which goes beyond the schema's type description.

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 a specific action: 'List scorecards submitted for a specific application.' This uses a clear verb and resource, and the scope ('specific application') distinguishes it from sibling tools like global listing tools or get_scorecard for individual scorecards.

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 concrete guidance on finding the required application_id via a lookup chain (search_candidates_by_name → get_candidate), implying when to use this tool. However, it doesn't explicitly state when not to use it or mention alternatives like get_scorecard.

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 states 'Read-only' explicitly, which is a key safety trait, and describes the return content (per-stage counts, conversion percentages, time-in-stage metrics). This adds valuable behavioral context beyond the tool name, though it does not cover error behavior or auth requirements.

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 four sentences, each earning its place: purpose, read-only status, example queries, and return details. It is front-loaded and free of fluff.

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 a simple one-parameter tool with an output schema, the description provides sufficient context: purpose, usage examples, prerequisite, and return metrics. It does not over-explain or omit critical operational details, though it could mention potential limitations (e.g., only for active jobs) but that is not necessary.

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% (job_id has a description). The tool description repeats the 'list_jobs → match by name' guidance already present in the schema, adding no new parameter-level semantics. Baseline of 3 is appropriate because the schema handles the parameter meaning.

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 it provides 'Conversion rates and stage metrics for a job' and specifies 'Returns per-stage counts, conversion percentages, and time-in-stage metrics.' It uses a specific resource (pipeline metrics) and is distinct from sibling tools like time_to_hire or source_effectiveness.

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 gives concrete example user queries ('what are our conversion rates for the Backend role?' or 'where are we losing candidates?') and explicit prerequisite instructions ('To find job_id: list_jobs → match by name'). It does not mention alternative tools or exclusions, but the usage context is clear.

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 explicitly states 'Read-only,' which is a key behavioral trait. It also discloses what data is returned (stages with candidate counts, names, days-in-stage, last activity). It doesn't mention rate limits or authorization requirements, but for a read-only aggregation tool, this is a reasonable level of 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 compact and well-organized. It starts with the core purpose, includes user-facing examples, provides a prerequisite step, outlines the return content, and ends with efficiency value. Every sentence adds meaningful information—no filler. It is front-loaded and easy to scan.

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 (one parameter, read-only, output schema present), the description is fully complete. It covers what the tool does, when to use it, how to get the required ID, what it returns, and why it's beneficial. The agent has all necessary context to select and invoke it correctly.

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 only parameter, job_id, already has a description in the schema ('Greenhouse job ID — list_jobs → match by name'), and the description reinforces this with a concrete workflow. Since schema coverage is 100%, the baseline is 3, but the additional context about how to obtain the job_id adds value, justifying a 4.

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 function: 'Complete pipeline view for a job — candidates grouped by stage.' It also provides user examples ('show me the pipeline for Backend Engineer') and conveys the resource (job pipeline). While it doesn't explicitly differentiate from siblings like pipeline_metrics, the 'Complete' framing and focus on stage grouping set it apart to some degree.

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 clear usage context with example queries ('how many candidates are in each stage') and a prerequisite workflow ('To find the job_id: list_jobs → match by name'). It also highlights a value proposition ('One call replaces 5-10 sequential API calls'). However, it does not explicitly mention alternatives or exclusions, so it stops short of full guidelines.

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?

Since annotations are absent, the description carries the full burden. It discloses the tool is read-only and returns extracted text from the most recent resume attachment, which is valuable. However, it does not mention edge cases like missing resumes or rate limits, leaving a small 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?

Three sentences, no filler. The main action is front-loaded, and each subsequent sentence adds distinct value: user intents, lookup method, and batch alternative.

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 single-parameter read tool with an output schema, the description covers purpose, usage guidelines, and safety without redundant return-value explanation. It is complete for an agent to select and invoke correctly.

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 candidate_id, and the description adds extra context by explaining how to obtain the ID via search_candidates_by_name. This enriches the parameter's meaning beyond the schema 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 clearly states the tool downloads and returns a candidate's most recent resume text. The verb 'Download and return' plus the specific resource 'resume text' makes the purpose unambiguous and distinguishes it from siblings like get_candidate or download_attachment.

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 how to find candidate_id via search_candidates_by_name and directs batch usage to batch_read_resumes. This provides concrete when-to-use and alternative 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, the description carries the burden of disclosure. It clearly states 'Write operation' and notes reversibility via unreject_application, but does not detail side effects like email sending or permission requirements.

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 compact and front-loaded: first line states purpose, then provides concrete usage context. Every sentence earns its place with no repetition 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 moderate complexity and presence of an output schema, the description covers the main workflow, reversibility, and alternatives. It could have mentioned prerequisites like stage constraints, but the current coverage is strong.

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%, but the description adds real value by explaining how to source parameters (application_id via search_candidates_by_name → get_candidate, rejection_reason_id via list_rejection_reasons, email template via list_email_templates), going well beyond 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 uses a specific verb (reject) and resource (candidate from a job), and explicitly labels it as a write operation. It also distinguishes itself from related tools like unreject_application and bulk_reject.

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 explicit when-to-use guidance, including a detailed workflow to obtain application_id and rejection_reason_id, and names alternatives (unreject_application for reversal, bulk_reject for bulk operations).

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?

The description discloses 'Read-only' (since no annotations are provided) and details the boolean search behavior: keywords (OR), required_keywords (AND), exclude_keywords (NOT with word-boundary matching). This goes beyond the schema and gives the agent a clear picture of side effects and matching rules.

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 well-structured: a clear purpose statement, a user-facing example, tool positioning, a prerequisite instruction, and a semantic explanation. It is compact with no unnecessary words, though it is slightly dense in one paragraph.

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 output schema documents return values, the description covers the essential usage guidance, search logic, source scope (resumes in pipelines), and readonly nature. It does not cover all edge cases, but it is sufficiently complete for effective selection and 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the semantic of OR/AND/NOT for the keyword parameters and the word-boundary matching nuance for exclude_keywords, which is not evident from 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 explicitly states the action ('Search resume text in pipelines for skills and qualifications') and provides example user queries ('find Rust engineers'). It distinguishes itself from siblings by positioning as 'the primary sourcing tool' with boolean search capabilities, making its purpose 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?

It gives clear usage context: 'The primary sourcing tool — ~90% of candidate data lives in resumes' and instructs to 'Pass job_ids (list_jobs → get IDs for similar roles)'. It does not explicitly name alternatives, but the positioning makes it clear this is the go-to tool for resume search.

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 explicitly marks the operation as read-only, which is a key safety trait. It also discloses that the tool aggregates and returns multiple data types (profile, resume, answers, etc.) in a single call, setting expectations for response breadth. No contradictions with annotations since none exist; however, it omits edge-case behaviors like error handling or permission requirements.

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 sentences with clear front-loading: the core function first, followed by usage scenarios and parameter acquisition, then return contents. Every sentence adds value; 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?

For a single-parameter tool with an output schema (though not displayed), the description thoroughly specifies the return value composition. The provided workflow for obtaining application_id ensures the agent can correctly invoke the tool even without prior context. Given the tool's complexity, the description covers the essential 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 covers application_id at 100%, but the description adds crucial guidance on how to obtain the ID via a specific tool chain (search_candidates_by_name → get_candidate → match). This goes beyond the schema's bare description and helps agents understand the semantic provenance of the parameter.

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?

Clearly states it is a 'full screening package' for one candidate application, with a specific verb and resource. Distinguishes itself from sibling tools like get_candidate or read_candidate_resume by emphasizing the aggregated, one-call nature. The read-only qualifier adds clarity.

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?

Directly addresses when to use it via example user intents ('screen Sarah...' or 'give me the full picture'). Provides a step-by-step alternative workflow to obtain application_id, implicitly guiding when this tool is the right choice versus using smaller sibling tools. Explicitly mentions the integration steps leading up to invocation.

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 discloses the read-only nature and states it 'Returns the candidate record directly'. It does not cover edge cases like no matches, but the core behaviors are transparent beyond the annotation absence.

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 concise sentences, front-loaded with the main action, and no extraneous detail. Every sentence adds value.

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 simplicity (one required parameter), the presence of an output schema, and the explicit usage alternative, the description is complete for an agent to select and invoke correctly.

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%, so the parameter description already provides meaning. The description reinforces the 'exact' nature of the email but does not add significant new semantics 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 clearly states 'Look up a candidate by exact email address' with a specific verb and resource, and explicitly distinguishes itself from the sibling tool 'search_candidates_by_name' by targeting email-based 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?

It explicitly states when to use this tool ('Use when the user provides an email instead of a name') and names the alternative for name-based lookup, providing clear contextual 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?

No annotations are provided, so the description carries full responsibility. It explicitly declares 'Read-only,' which is a safety-relevant behavior not available elsewhere. It also discloses that matching is case-insensitive and substring-based, with concrete examples, and notes that users refer by name rather than ID—all beyond the structured 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?

Three sentences, front-loaded with purpose, then workflow, then an illustrative example. Every sentence earns its place without redundancy, making it concise yet highly informative.

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 simplicity of the tool, a fully documented schema (100% coverage), and the presence of an output schema, the description covers purpose, usage, and behavior completely. Pagination is not discussed, but the schema documents per_page and max_pages, so no critical gap exists.

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 the baseline is 3. The description's example ('Sarah') reinforces the schema's 'case-insensitive substring' but adds no new parameter-specific information beyond what the schema already states. Per_page and max_pages are not mentioned in the description, but their schema descriptions are clear.

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 'Find candidates by name,' which is a specific verb plus resource. It further positions itself as 'the starting point for most workflows,' distinguishing it from other search tools by name-based scope. The matching behavior (case-insensitive substring) is also clarified, leaving no ambiguity about what the tool does.

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 states 'Use this first whenever a user mentions a candidate, then get_candidate on the match to see their full profile and application IDs.' This provides a clear workflow and when-to-use instruction relative to get_candidate. It also implies the alternative (email search) by noting users refer to candidates by name, not 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 full burden. It explicitly states 'Read-only,' clarifying that no mutations occur. It also discloses the limitation that results depend on populated structured data. Missing finer behavioral details like rate limits or pagination, but the core safety profile is transparent.

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 concise and front-loaded with the core purpose. The subsequent sentences provide examples, usage instructions, and alternative recommendations—all in a tight paragraph. 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?

Given the tool's complexity (8 parameters, output schema present), the description provides sufficient context: what it does, when to use it, when to switch to alternatives, and how to prepare inputs. It does not need to explain return values because an output schema exists.

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%, with each parameter having a clear description including examples (e.g., title_keywords '['VP', 'Director']'). The tool description adds contextual examples but does not explain parameter interactions beyond the schema. Thus it meets the baseline for high schema coverage without adding substantial parameter-level insight.

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 function: 'Search pipelines by structured fields — title, company, education, tags' and explicitly labels it 'Read-only.' It distinguishes itself from the sibling tool scan_pipeline_resumes by positioning this as structured-field search.

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 explicit usage context with natural-language examples ('find VP-level candidates', 'who do we have from Google?'), instructs to pass job_ids obtained via list_jobs, and names an alternative (scan_pipeline_resumes) for when this tool underperforms. Also suggests combining with batch_read_resumes for verification.

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. It explicitly declares 'Read-only', which is a key behavioral safety disclosure, and explains behavior around job_id filtering and returning metrics. It does not cover pagination or permission details, but is transparent about its main safety profile and output.

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 short sentences front-loaded with the core purpose, followed by usage triggers and parameter guidance. Every sentence earns its place with no filler or 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?

With an output schema present, the description does not need to explain return values, but it still does. It covers what the tool does, when to use it, and how to parameterize it. Low parameter count and simple nullable inputs mean the context is 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 has 100% description coverage, so the baseline is 3. The description adds context for job_id (omit for org-wide analysis, list_jobs→match by name) beyond the schema, but does not mention created_after, which the schema already describes as ISO 8601. Overall, the description adds modest value on top of 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 clearly states the tool analyzes candidate sources by effectiveness, with explicit output metrics (volume, active rate, hire rate per source). This distinguishes it from sibling analytics tools like pipeline_metrics or time_to_hire, which focus on other aspects of the recruitment pipeline.

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 trigger phrases ('which sources are working?', 'where should we spend recruiting budget?') and explains when to pass job_id vs omit for org-wide analysis. However, it does not name alternatives or provide exclusion criteria, so it falls short of a 5.

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 present, so the description carries the full burden. It explicitly states 'Read-only' and discloses sorting by stalest. However, it does not mention pagination behavior, rate limits, or auth requirements. For a read-only listing tool, the essential safety and ordering behavior is covered, but other traits are left to the output 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?

The description is three crisp sentences: first states purpose and read-only nature, second gives a user scenario and workflow, third explains job filtering. Every sentence earns its place; there is no redundancy or filler, making it highly effective and scannable.

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 listing tool with an output schema and fully documented parameters, the description covers purpose, read-only nature, sort order, a concrete use case, and a filtering instruction. It does not explicitly state that omitting job_id returns applications across all jobs, but that is inferable. This is complete enough to enable correct 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces job_id semantics by referencing 'list_jobs → match by name', but this repeats what the schema already says. It adds no new parameter-level meaning for days or limit, so it provides marginal value 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 a specific verb+resource combination: 'Applications with no activity for N days, sorted by stalest' clearly states the tool lists stale applications and defines the criterion. It distinguishes from siblings like list_applications by the inactivity filter and sorting behavior, making the purpose 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 explicit usage context: 'Users say "who's been sitting untouched?"' and recommends pairing with bulk_reject for pipeline cleanup. It also instructs how to filter by job via 'list_jobs → match by name'. It lacks explicit exclusions (e.g., 'use list_applications for unfiltered views') but gives sufficient, actionable scenarios.

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 takes on the full burden of behavioral disclosure. It clearly states 'Read-only' upfront, signaling a safe read operation. It also describes the return values (average, median, min, max days) and the scope (hired candidates). While it doesn't mention rate limits or data freshness, the read-only nature is sufficiently transparent.

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 four lines, front-loaded with purpose, and every sentence earns its place: purpose, read-only flag, example queries, parameter guidance, and output summary. No redundancy or fluff.

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 read-only metrics tool with two optional parameters, the description covers all essential aspects: what it does, how to filter, what it returns, and safety. With an output schema present and a clear description, the agent has everything needed to select and invoke the tool correctly.

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 both parameters described. The description adds value by explaining that omitting job_id yields org-wide metrics, which is not present in the schema's 'default null'. This extra context helps the agent understand the filter vs. global behavior 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 clearly states the tool provides 'Time-to-hire metrics for hired candidates', which is a specific verb+resource combination. It distinguishes itself from siblings like pipeline_metrics by focusing on hired candidates and days-to-offer. Including example user queries ('how long does it take to hire?') further clarifies its purpose.

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 tells users when to use the tool via natural language examples ('Users say "how long does it take to hire?"'). It also provides clear scoping instructions: pass job_id for one role, omit for org-wide metrics, and cross-references list_jobs for ID lookup. This is actionable guidance with no ambiguity.

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 must disclose behavior; it explicitly labels the operation as a 'Write operation,' which is critical for an agent to know. It also states the resulting state change ('returning the candidate to active status'), but doesn't address permissions, idempotency, or side effects beyond that.

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 brief and front-loaded, with the purpose in the first sentence. The additional examples and workflow are purposeful and directly support usage, with no wasted words.

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 single-parameter write operation with an output schema, the description covers the core purpose, the write nature, and the parameter acquisition workflow. It's sufficiently complete for an agent to understand and invoke, though it doesn't cover edge cases like calling on an active application.

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 describes application_id as a Greenhouse application ID, but the description enriches this by showing how to find it via search_candidates_by_name → get_candidate and how to map natural language to the parameter. This adds meaningful guidance 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 opens with 'Reverse a rejection, returning the candidate to active status,' which clearly states the action and its effect. It distinguishes from the sibling reject_application by being the inverse operation, and gives concrete user phrasings.

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 explicit examples of user intents ('undo the rejection for Sarah' or 'bring Sarah back') that trigger this tool. It also specifies a workflow to obtain the required application_id, setting clear context for when to call this tool, though it doesn't explicitly mention exclusions or alternatives.

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