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

Annotations provide idempotentHint=false and destructiveHint=false. The description adds behavioral context beyond annotations: the note will be visible to the hiring team and the response includes note_id and a confirmation message. This gives the agent useful expectations without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler. It front-loads the action, then states purpose and usage, then closes with the response format. 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 two-parameter write tool, the description covers purpose, usage context, visibility of the note, and the response shape. It does not mention prerequisites (e.g., candidate existence) or error conditions, but given the schema and annotations, the description is near-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?

Schema description coverage is 100%, so baseline is 3. The description adds value by framing the note as an 'evaluation note' meant for assessments/recommendations, which clarifies the intended use of the 'note' parameter beyond its schema description. It does not duplicate parameter details.

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 (Add an evaluation note to a candidate) and the resource (candidate), and it explains the note's purpose (record assessment/recommendations). It distinguishes itself from sibling ashby_add_candidate_tag by specifying it is an evaluation note, not a tag.

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 when-to-use context: 'Use this to record your assessment or recommendations.' It does not, however, explicitly mention alternatives (e.g., ashby_add_candidate_tag) or state when not to use this tool, so it lacks explicit exclusions.

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?

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is known. The description adds the response format (confirmation message) and the prerequisite, which are useful but not deeply behavioral. It does not disclose side effects like whether tagging replaces existing tags, but this is minor given the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficient: a single-sentence action with examples, a one-line usage context, a prerequisite note, and a response note. Every sentence earns its place, and the core action is front-loaded. 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 simple two-parameter tool with annotations covering safety, the description is complete. It specifies the response format and the prerequisite for the tag ID. It does not discuss error handling or edge cases, but that is not necessary for a straightforward tagging action. The tool is adequately specified for an agent to call 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 coverage is 100% and both parameters have clear descriptions (tag_id as UUID from admin settings, candidate_id as UUID). The description reinforces the source of tag_id but adds no new meaning beyond the schema. Baseline 3 is appropriate when schema carries the full parameter documentation.

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 (tag) and resource (candidate) with concrete examples of labels. It clearly differentiates from the sibling ashby_add_candidate_note, which is for notes, by focusing on categorizing via tags. An agent can immediately understand what action to take without confusion.

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 says to use this during evaluation, providing a clear context. It also states a prerequisite (tag ID from admin settings). However, it does not explicitly mention when not to use it or alternative tools, though the sibling list makes the distinction from note-taking obvious.

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?

Annotations (idempotentHint=false, destructiveHint=false) are not contradicted. The description clearly states side effects: creates a candidate, adds a lead application, optionally attaches a note. It also discloses the response shape (candidate_id, application_id, note_id). This is good transparency for a creation tool, going beyond annotations by specifying what gets created.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise paragraphs. The core purpose is front-loaded, and the response format is summarized. No wasted words; every sentence contributes. Slightly longer than necessary but 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 write operation with 6 parameters (2 required) and no output schema, the description covers the workflow and response. It explains optional note and the overall effect. It could mention prerequisites (e.g., job must exist) but that is implicit in the schema. Sufficient for an agent to 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 description coverage is 100%, so parameters are already fully documented. The description adds a bit of context (e.g., note is for sourcing context and visible to hiring team) but doesn't go beyond schema. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds minimal extra semantic value.

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 verb+resource: 'Create a new candidate and add them as a lead on a job.' It also gives a use case (sourcing from LinkedIn) and distinguishes from sibling tools that read or add notes/tags. The purpose is unambiguous and immediately actionable.

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 says 'Use this to source candidates... directly into Ashby,' giving a clear context. It describes the flow (creates candidate, adds lead, optionally note). It doesn't explicitly list alternatives or when not to use, but the sibling list makes it obvious that this is the primary creation tool. Minor gap: no mention of when to prefer other add-tools like add_candidate_note.

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?

Beyond the destructiveHint annotation, the description reveals useful behavior: it automatically resolves the 'Archived' interview stage and can send a rejection email. It also lists the response fields, which is helpful because there is no output schema. It does not expand on reversibility or side effects, but the annotation already signals destructiveness.

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, purposeful sections: a one-sentence action statement, a workflow, and a response shape. No filler or redundant restatement of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-application mutation with 100% schema coverage and destructiveHint, the description is nearly complete: it gives the workflow, automatic stage resolution, and response fields. It could add guidance on sourcing application_id or when to use bulk_archive, but those are not required to call this 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%, so the schema carries the detailed parameter meanings. The description adds value by linking archive_reason_id and email_template_id to the specific list tools that produce them and clarifying the optional 'reason' and 'rejection email' concept.

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 and resource: 'Archive an application' with optional reason and rejection email. It is clear but does not explicitly distinguish itself from sibling ashby_bulk_archive or ashby_move_application_stage, so it misses the top score for explicit sibling differentiation.

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 a concrete workflow with prerequisite calls to ashby_list_archive_reasons and ashby_list_email_templates before invoking this tool. It does not explicitly state exclusions or when to prefer ashby_bulk_archive, but the sequencing and prerequisite guidance are 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?

The destructiveHint annotation already signals the operation is destructive, and the description adds batch limits, reusable archiving logic, a caching optimization, and the response shape. It does not go deeper into side effects such as partial failures or how sending emails behaves beyond the schema, so the extra behavioral context is moderate rather than rich.

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 and front-loaded: first the action, then limits and relationship to the sibling tool, then the return format. No sentence is filler; the response format is valuable because there is no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive batch operation with no output schema, the description provides the essential invocation context: batch limit, relation to the singular tool, and the exact response shape. It could add an explicit note about the interplay between send_email and email_template_id, but that dependency is already 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 description coverage is 100%, so the parameters are already fully documented. The description adds only general framing ('optional reason and rejection email') and the 25-ID limit, which is also in the schema; that meets the baseline but does not go beyond it.

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: 'Archive multiple applications at once,' and clearly frames this as the bulk version of ashby_archive_application. It names the sibling tool and says it uses the same archiving logic, so an agent can tell them apart immediately.

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 makes the batch use case clear and explicitly ties the behavior to ashby_archive_application, which implies the singular tool is the alternative for one-off archiving. It does not explicitly state when-not conditions or directly compare the two tools, but the routing is easy to infer.

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 adds useful behavioral context beyond the destructiveHint annotation by stating that auth, retries, and timeouts are handled automatically and that the raw Ashby response is returned with success, results, pagination fields, and error details. It does not explicitly warn that arbitrary endpoints may mutate or delete data, but destructiveHint already covers that risk; the description adds enough additional context to earn a 4.

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 organized into short, purposeful paragraphs: purpose and examples, usage rules, prerequisite docs, and behavior/output. Every sentence adds value, and the core purpose is front-loaded in the first sentence.

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 complexity of an arbitrary API endpoint tool and the absence of an output schema, the description covers the essential aspects: when to use it, how to discover parameters, automatic handling of auth/retries/timeouts, and the shape of the response. It could be slightly more complete by explicitly cautioning that some endpoints have side effects beyond what the endpoint name suggests, but the destructiveHint annotation partially covers that.

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 parameters endpoint and params are already well documented. The description itself repeats the example endpoint format and refers to ashby_get_api_docs for per-endpoint parameter names, but adds little beyond the schema. This meets the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Call any Ashby API endpoint directly') and clearly positions itself as an escape hatch for endpoints not wrapped by the narrow ashby_* tools, listing concrete examples like offer.list and candidate.update. This differentiates it from all sibling tools without requiring schema inspection.

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?

Explicit guidance is given: prefer a dedicated tool when one exists, use this tool only when no dedicated tool covers the endpoint, and call ashby_get_api_docs first if unsure. This directly answers when to use versus alternatives, leaving little to inference.

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?

Annotations already mark readOnlyHint=true, and the description reinforces this with 'Return a reference,' which is a read-only action. It goes beyond the annotation by detailing what the reference contains (base URL, auth, response envelope, pagination, endpoint index, gotchas), making the tool's behavior concrete. No contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff. The first front-loads the core purpose and deliverables; the second gives a practical usage directive and a link. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only documentation tool with no output schema, the description fully specifies the returned content and when to invoke it. The pointer to official docs and the advisory to call before ashby_call_api leave no gaps for an agent deciding how to proceed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema is trivially complete (100% coverage). Per the rubric, a 0-parameter tool gets a baseline of 4. The description adds no parameter details because there are none to document, which 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 ('Return a reference'), names the resource ('Ashby API'), and lists the exact contents (base URL, auth, response envelope, pagination, endpoint index with parameter hints and gotchas). It clearly distinguishes this tool from the many operation-focused siblings by identifying it as the documentation/reference tool and even names the closely related sibling ashby_call_api.

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 use this tool: 'Call this before ashby_call_api when you're unsure which endpoint or param names to use.' This gives a clear precondition and names the alternative, leaving no ambiguity about routing. It also provides the official reference URL as a fallback.

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?

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds that it fires four API calls concurrently for speed, which is a useful behavioral detail (e.g., potential rate-limit impact). It also specifies the response structure, adding value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus a response line, with no redundancy. It front-loads the purpose and adds essential operational detail (concurrency and response shape) without excessive length.

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-application fetch tool, the description is complete: it lists the response fields, notes the concurrent API calls, and the read-only annotation covers safety. There is no output schema, so the response description compensates adequately.

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 fully documents application_id as a UUID to fetch, with 100% coverage. The description does not add additional parameter semantics, but none are needed since the schema is self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves full application details and enumerates the specific components (stage history, hiring team, feedback, criteria evaluations). It also explicitly says to use it to deep-dive into a specific application, which distinguishes it from list tools like ashby_list_applications and more targeted getters like ashby_get_feedback.

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 a clear usage context: 'Use this to deep-dive into a specific application.' This implies when comprehensive details on a single application are needed rather than a list or a single component. However, it does not explicitly name alternatives or state when not to use it, so it's clear but not exhaustive.

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?

Annotations already declare readOnlyHint=true, and the description does not contradict that. The description adds valuable context about the nature of the returned data (candidate's written answers) and the response fields (application_id, candidate_name, job_title, form_responses), which goes beyond the annotation. It does not disclose potential edge cases (e.g., empty form), but for a read-only 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 efficient and well-structured: the first sentence states the core purpose, the second provides usage guidance, and the third lists the response fields. Each sentence adds distinct value with 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 simple read-only tool with one parameter and no output schema, the description is complete. It explains what data is returned, gives usage context, and differentiates from siblings. There is no missing information an agent needs to call 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 input schema already provides a full description for the single parameter (application_id), so schema coverage is 100%. The description reinforces that it fetches responses 'for a specific application' but adds no new syntax or format details. Baseline 3 is appropriate since the schema carries the semantic weight.

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 ('Get'), the resource ('application form responses'), and the scope ('for a specific application'). It explicitly differentiates from sibling tools by clarifying it returns the candidate's submitted written answers (screening questions, cover letter, etc.), which distinguishes it from get_application_details and get_resume.

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 this to read what a candidate actually wrote in their application.' It also names preceding tools ('Use after ashby_list_candidates_for_job or ashby_get_application_details') and the goal ('evaluate a candidate's application content'), giving clear context and routing.

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?

Annotations already indicate readOnlyHint=true, and the description adds valuable context: it fetches the candidate profile and then resolves each application for full details, implying a multi-step read operation. It also documents the response shape, which is helpful beyond the annotation since there is no 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 well-structured and front-loaded with the primary purpose, followed by concise content details and a clear response outline. No redundant filler or vague language is present.

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 no output schema, the description is complete: it identifies the input, describes the candidate profile contents, and specifies both the candidate and application response fields. An agent has enough information to invoke the tool correctly and interpret its result.

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 candidate_id already described as 'The candidate ID (UUID) to fetch.' The description does not add additional parameter-level meaning, so it meets the baseline but does not exceed it.

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 ('Get a comprehensive candidate profile') and enumerates the included data: candidate details, contact info, social links, tags, source, and applications with stages. This distinguishes it from siblings like get_candidate_notes or get_application_details because it frames itself as the full-profile retrieval tool.

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 conveys a clear use case: 'everything needed to evaluate a candidate', suggesting this is the go-to tool for a broad candidate overview. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the context is unambiguous enough for an agent to select it appropriately.

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?

Annotations already declare readOnlyHint=true, and the description adds domain context (notes are evaluation comments) and response shape (notes[] with id, content, createdAt, author). This enriches the behavioral picture beyond the annotation alone, though it doesn't cover edge cases like pagination or errors.

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, each with a distinct purpose: action, use case, and response structure. It is front-loaded with the core verb and contains 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 simple read-only list tool with one documented parameter and a response shape described in the text, the description is fully sufficient. The annotations cover safety, and the description tells an agent what it returns and when to use it.

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%: candidate_id is already fully described as 'The candidate ID (UUID) to fetch notes for.' The description adds no additional parameter meaning beyond the schema, so the baseline 3 applies.

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 'List all notes on a candidate,' a specific verb+resource statement. It clarifies the content as 'evaluation notes or comments left by the hiring team,' distinguishing it from the sibling ashby_add_candidate_note (which writes notes) and other getter 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 provides clear usage context: 'Use this to see existing evaluation notes or comments left by the hiring team.' It does not explicitly name alternatives or exclusion criteria, but the read-only versus add-note sibling is implied by the wording.

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 readOnlyHint=true already conveying the safe read-only nature, the description adds useful behavioral detail about the response: feedback[] with form definition and submitted values. This is helpful because there is no output schema, and it clarifies what the caller can expect.

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, stating the action first, then the use case, then the response shape. Each line contributes meaningful information 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 one-parameter read-only tool, the description fully covers what the tool does, why to use it, and what the response looks like. No output schema exists, but the response summary compensates sufficiently.

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%; the single parameter application_id is already fully documented in the schema. The description does not add further parameter semantics, so the baseline of 3 applies.

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 ('get'), the resource ('submitted feedback/scorecards'), and the target ('an application'). This is distinct from sibling tools like ashby_get_application_details and ashby_get_application_form_submission because it explicitly centers on interviewer evaluations and scores.

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 a clear usage context: 'Use this to review interviewer evaluations and scores.' It stops short of explicitly naming alternatives or exclusion conditions, but the intended scenario is unambiguous for a simple lookup 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?

The description discloses behavioral traits beyond the readOnlyHint annotation: it states that the tool 'fetches the job, resolves the job posting description, and interview plan stages automatically.' It also lists the response structure, giving the agent a clear picture of what will be returned. No contradictions with annotations; it only adds context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise, consisting of three sentences: purpose, usage context, and response format. It front-loads the core purpose and includes only essential information with no redundant phrasing. 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, read-only tool with one parameter and no output schema, the description is largely complete. It covers purpose, usage, behavior, and response structure. Minor omissions like error handling are not critical for this straightforward operation, making it adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes the single parameter (job_id) as 'The job ID (UUID) to fetch details for.' with 100% coverage. The tool description restates that it's for a specific job but adds no new semantic details about the parameter itself. With full schema coverage, the baseline of 3 applies.

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: getting full details for a specific job, explicitly listing what's included (description, interview plan stages). This distinguishes it from sibling tools like ashby_list_jobs (which lists jobs) and ashby_get_application_details (which gets application details). The verb 'Get' plus the specific resource 'full details for a specific job' makes 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?

Provides explicit usage guidance: 'Use this after ashby_list_jobs to understand a position's requirements and hiring pipeline.' This gives a clear trigger condition and sequencing. However, it does not explicitly contrast with alternatives or state when not to use it, so it stops 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?

In addition to the readOnlyHint annotation, the description discloses that the server fetches and aggregates all applications and removes pagination overhead. It also previews response structure. No contradiction with annotations was found.

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: a declarative summary, usage examples, an aggregation note, and a response shape. Every sentence earns its place and the most important information comes first.

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 only two optional parameters fully documented in the schema, readOnlyHint present, and no output schema, the description still provides the return shape and explains aggregation/pagination behavior. This is sufficient for an agent to call 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 both job_id and status already have clear descriptions, defaults, and enum. The tool description does not add parameter-level meaning beyond that, so a 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 opening sentence names a specific verb and resource: get a pipeline summary with candidate counts per interview stage per job. The example questions ('What does our pipeline look like?') further anchor its purpose and distinguish it from raw list tools like ashby_list_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?

The description gives concrete trigger questions and explicitly notes that the MCP server aggregates internally so no manual pagination is needed. It does not state exclusions or name sibling alternatives, but the intended use cases are 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?

Annotations declare readOnlyHint=true, so the read-only nature is already provided. The description adds valuable behavioral details: it fetches the file URL, downloads, and returns text content; supports PDF, DOCX as plain text, and plain text; for unsupported formats returns the download URL. This goes beyond annotations and clarifies output behavior. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: first sentence states purpose, second gives usage context, third explains the process, fourth lists supported formats, and fifth describes the response. No fluff, front-loaded with key info.

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 no output schema, the description explains the response format (filename, content, or url). It covers supported formats, usage sequence, and parameter handling. It doesn't mention error handling or timeouts, but for this tool with simple params and read-only annotation, it's sufficiently complete for an agent to 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 description coverage is 100%, with both parameters (file_handle, file_name) already described clearly. The description reinforces the file_handle source and mentions file_name helps determine format, but adds little beyond the schema. 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 the action (download and read) and resource (candidate's resume or uploaded file). It explicitly differentiates from siblings like ashby_get_candidate by specifying it reads file content, and mentions usage after getting the candidate. This is a specific verb+resource with clear scope.

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 usage context: 'Use this after ashby_get_candidate to read the actual content of a resume or file.' It also explains the prerequisite (file handle from candidate's fileHandles array). It doesn't explicitly list alternative tools or exclusions, but the context is clear enough for an agent to select it appropriately.

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?

Annotations include readOnlyHint=true, so the description doesn't need to restate safety. It adds valuable context: which filters are server-side vs. client-side, and the response structure (items[] with fields, has_more, next_cursor) which is not fully covered by annotations. This goes beyond the annotation's basic read-only hint.

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, front-loaded with purpose and filters, then includes example queries and response format. Every sentence adds value—no fluff. The structure is logical: what, when, implementation note, response.

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 listing tool with 9 parameters (all optional), the description covers intended use cases, filter behavior, and response shape. However, it doesn't explain the interplay between status and stage filters (e.g., whether they are combined with AND), nor does it mention pagination details beyond cursor/has_more. Still, given the output schema is absent and parameters are extensive, it does a good job of orienting an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema by clarifying that date and status filtering are server-side (efficiency) while stage and source are client-side (applied by MCP server). This helps agents understand performance implications and where filtering occurs, which the schema alone doesn't convey.

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 lists applications across all jobs, with explicit filters (date, status, stage, source). It differentiates itself from siblings like ashby_list_candidates_for_job and ashby_get_application_details by focusing on cross-job listing with filtering.

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 example questions that signal when to use the tool, and mentions that date/status filtering is server-side while stage/source is client-side. However, it does not explicitly mention when NOT to use it or point to alternatives like ashby_list_candidates_for_job for job-scoped lists.

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?

Beyond the readOnlyHint annotation, the description discloses the required API key permission ('hiringProcessMetadataRead') and explicitly states that the output contains reasons to pass to ashby_archive_application. It also documents the response structure, which is important since no output schema is provided.

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-front-loaded, stating the core action first, then usage context, permission requirements, and response format. Every sentence adds necessary information without 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?

For a zero-parameter, read-only listing endpoint, the description is complete: it states purpose, when to use it, permission requirements, and the exact response fields. No output schema exists, and the description compensates by naming the fields (id, text, reasonType).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there are no parameter semantics to clarify. The baseline of 4 applies because there is nothing missing on the parameter side, and the description reasonably focuses on the output and usage instead.

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 operation: list available archive/rejection reasons. It distinguishes itself by positioning the tool as a prerequisite for ashby_archive_application and by specifying the output shape, so an agent understands exactly what it returns.

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 says to use it 'as the first step when archiving a candidate', which is clear contextual guidance. However, it does not mention when not to use it or name any alternative list tools, so it stops short of full when/when-not/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?

Annotations already provide readOnlyHint=true, and the description adds useful behavioral context: it lists return fields, explains pagination via cursor, and implies a read-only listing operation. It does not cover details like rate limits or error cases, but the annotation covers the main safety profile.

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 with the core purpose, followed by return details and pagination guidance. It is slightly redundant (return fields repeated in prose and in the response snippet) but every sentence carries useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (3 params, read-only, no output schema), the description covers the essential: what it returns, how to paginate, and its primary use case. It does not mention error handling or ordering, but these are not critical for a basic list endpoint.

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 schema fully documents all parameters. The description adds only minimal semantic value by mentioning 'Pass next_cursor to paginate,' which clarifies the cursor's role but does not significantly exceed 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+resource ('List all candidates/applications for a specific job') and clearly indicates the job-scoped scope. It does not explicitly name sibling alternatives or contrast with ashby_list_applications, so it misses the full sibling differentiation required for a 5.

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?

'Use this to see the pipeline for a job' gives a clear, explicit usage context. It does not enumerate exclusions or alternatives (e.g., when to use ashby_list_applications or ashby_get_pipeline_summary instead), stopping short of the strongest 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?

Annotations only provide readOnlyHint=true. The description adds the API permission requirement ('hiringProcessMetadataRead') and the response format (templates[] with id and name). This goes beyond annotations and is useful for the agent to know side effects and constraints.

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, with the core purpose front-loaded, followed by usage, permission, and response. Every sentence adds value and there is 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?

Given no parameters, a readOnly annotation, and no output schema, the description covers the essential aspects: what it lists, why you'd use it, the required permission, and the response structure. 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?

There are no parameters, so the schema is fully covered. The description doesn't need to add parameter details. The baseline for zero params is 4, and the description adds no unnecessary info.

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' and the resource 'email templates', and specifies their purpose 'for rejection/archive emails'. It also explicitly ties the tool to its sibling ashby_archive_application, distinguishing it from other list tools like ashby_list_jobs.

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 a specific usage scenario: 'Use this to find the template ID to pass to ashby_archive_application when sending a rejection email.' This tells the agent when to use it. However, it doesn't explicitly mention when not to use it or list alternatives, but the context is clear enough.

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?

It goes beyond the readOnlyHint annotation by disclosing the internal behavior: 'Fetches all interview plans, then resolves stages for each.' It also describes the response shape, which is useful since there is no 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?

Every sentence earns its place: the action, the use case, the internal behavior, and the response format. It is front-loaded with the core purpose and contains 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 zero-parameter read-only tool, the description is complete. It explains the response shape, how the tool works internally, and how the results should be used, leaving no obvious gap for an agent to 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?

There are zero parameters, so the baseline is 4 and there is no parameter gap to compensate for. The description adds useful context about the response structure even though parameter documentation is unnecessary here.

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: 'List all interview stages across all interview plans.' It also differentiates itself from sibling tools by clarifying this returns plan-level structure rather than candidate-level or upcoming interview data.

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 says exactly when to use this tool: 'to understand the hiring pipeline and get stage IDs for ashby_move_application_stage.' It provides clear context but does not explicitly mention when not to use it or name alternatives, so it stops 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?

The readOnlyHint annotation already marks this as safe, and the description adds meaningful runtime behavior: the paginated list contract with has_more and next_cursor. It is transparent about the returned wrapper without going beyond what an agent needs.

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 front-loaded sentences state purpose, use case, and response shape with no filler. The response line earns its place because there is no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool, the description captures purpose, pagination behavior, and the response envelope completely. Combined with the self-describing schema and readOnly annotation, an agent has what it needs to invoke the tool and interpret results.

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 schema already documents limit, cursor, and status clearly. The description's mention of next_cursor reinforces pagination but does not add material meaning beyond the existing parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence identifies a specific verb and resource ('List jobs from Ashby') and enumerates returned fields, making the core action unambiguous. It stops short of an explicit sibling comparison, though 'before looking at candidates' differentiates it from candidate-oriented 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?

'Use this to discover what positions exist before looking at candidates' gives a clear intended use case and implies a candidate-search workflow context. It does not name specific alternatives or state when not to use it, but it provides enough placement 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?

The description adds behavioral detail beyond the readOnlyHint annotation: it states that the tool "fetches interview schedules, resolves candidate and job details, and filters by date range," and it describes the response structure in terms of items[] and their fields. This gives an agent a clear picture of what happens and what to expect, though it stops short of discussing edge cases or exact filtering semantics beyond what the schema already says.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then gives practical usage examples, then explains the internals and the response shape. Each sentence contributes value, and the response structure is included because there is no output schema to rely on. It is slightly longer than strictly necessary but not padded or repetitive.

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 that the tool has 4 optional parameters and no output schema, the description compensates well by describing the response items and their fields. It also explains that candidate and job details are resolved, which helps agents understand the output. It lacks only minor details like pagination behavior beyond the limit parameter, but overall it is complete enough for an agent to call 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 description coverage is 100%, so the parameters are already fully documented with types, defaults, enum values, and descriptions. The description's phrase "filters by date range" merely restates the start_after/start_before parameters and does not add any new meaning beyond the schema's own per-parameter descriptions. A baseline 3 is appropriate here.

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, "List upcoming and pending interview schedules," and immediately gives concrete example queries that show exactly what the tool does. It is clearly distinct from siblings: no other sibling tool claims to list interview schedules; ashby_list_interview_stages is about stages, not schedules.

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 with example questions like "What interviews do I have this week?" and "Who needs to be scheduled?", which strongly signals when to use it. However, it doesn't explicitly mention which sibling tools are alternatives or when to prefer them, so it lacks a clear when-not-to-use statement.

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 destructiveHint annotation marks the operation as state-changing, and the description adds useful behavioral context: only active transitions are supported, archived stages require an archive reason, and the response returns the updated application with the new current_stage. No contradiction with the annotation.

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, each serving a purpose: statement of action, use case, stage-ID source and archived caveat, and response shape. No filler 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 two-parameter action with a destructive annotation and no output schema, the description covers what it does, how to get required IDs, when not to use it, and what response to expect. 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% and both parameters are already described with IDs and intended values. The description adds that stage IDs come from ashby_list_interview_stages, which is helpful, but otherwise does not meaningfully extend the schema details.

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 ('Move an application to a different interview stage') and clarifies its role as advancing candidates through the pipeline. It also distinguishes itself from archive operations by stating archived transitions need an archive reason and are out of scope.

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 when-to-use guidance (advancing candidates) and tells the agent where to get stage IDs. It states a when-not case (archived-type stages require an archive reason; use only for active transitions), though it does not explicitly name the archive_application sibling as the alternative for archiving.

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?

Annotations already declare readOnlyHint=true, so the description doesn't need to restate that. The description adds useful behavioral context: the AND logic between name and email, the max 100 results cap, and the response shape (candidates[] with id, name, email, phone). It doesn't mention pagination or rate limits, but for a read-only search tool this is reasonably 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 compact and front-loaded: the first sentence states the action, the second gives the usage context, and the third covers logic and limits. Every sentence earns its place with 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 read-only search tool with 100% schema coverage and no output schema, the description covers the key decision factors: when to use it, the AND logic, the result cap, and the response fields. It could mention pagination or what happens when no results are found, but those are minor gaps given the tool's simplicity.

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 schema already documents all three parameters. The description adds the AND logic between query and email, which is a meaningful semantic detail beyond the schema. However, it doesn't add much beyond that, 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 states a specific verb ('Search') and resource ('candidates') and clearly identifies the search criteria (name or email). It distinguishes itself from sibling tools like ashby_get_candidate (which likely fetches by ID) by explicitly noting this is for when you know name/email but not ID.

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 says when to use this tool: 'when you know a candidate's name or email but not their ID.' This directly differentiates it from ashby_get_candidate and other candidate-related tools. It also clarifies the AND logic when both name and email are provided, and the max result limit.

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