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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation/safety profile is already covered. The description adds genuinely new context — Claude-authored notes are signed with the configured author name — which helps the agent understand provenance. It still says nothing about what happens with is_sensitive notes or any 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?

Two short sentences, purpose first, behavioral nuance second. No filler and nothing that would waste an agent's 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 write tool with no output schema and zero schema-level parameter descriptions, the definition is thin: it omits what is_sensitive does, whether notes are visible to candidates, and what the call returns. Only the author-signing detail is added.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and does not. The ambiguous flag 'is_sensitive' is never explained, and neither 'note' nor 'job_application_id' is clarified beyond what their names imply.

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 gives a clear verb and resource ('Add a note to a candidate's timeline'), so an agent knows exactly what the tool does. It does not explicitly contrast itself with the sibling bulk_add_notes, so the singular-vs-bulk distinction is left to inference from the tool name.

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?

There is no statement of when to use this tool versus bulk_add_notes, nor any prerequisites or exclusions. The only context given is a behavioral detail about note signing, not usage guidance.

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

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

Annotations supply the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description need not restate that. However, for a bulk write it discloses nothing about failure semantics (all-or-nothing vs partial), duplicate-note behavior, or the 200-item cap implied by the schema—context an agent calling a bulk mutation genuinely 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?

A single front-loaded sentence with the bulk semantics and illustrative examples; nothing is padded. It is efficient, though the brevity contributes to the missing behavioral detail noted elsewhere.

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?

There is no output schema and no annotations describing mutation semantics, yet a bulk-write tool of this shape needs to address capacity limits, per-item failure handling, and the is_sensitive field. The description covers the happy-path intent only, which is thin for a 200-item mutation.

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

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

Schema description coverage is 0% and there is one top-level array parameter, so the description carries some burden. It does convey the critical pairing model (one note per candidate) and gives example note text, but says nothing about the per-item fields job_application_id or is_sensitive, leaving the sensitivity flag entirely unexplained.

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 and resource ('Add one note per candidate in one go') and makes the bulk nature explicit, which cleanly separates it from the sibling add_note (single) and bulk_move_candidates (different resource). The examples of note content further pin down what a 'note' is here.

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 phrase 'in one go' plus examples like a screening summary or 'rejection email sent on <date>' imply the intended bulk-recording scenario, but the description never states when to prefer this over add_note or whether a single-candidate call should use this tool. Usage is implied rather than instructed.

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 cover safety (readOnly=false, destructive=false, idempotent=true), but the description adds genuinely non-annotation context: it is rate-limited, it continues past individual failures, and it requires user confirmation. It stops short of saying how partial failures are surfaced or whether auth/permission scoping applies.

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 tight sentences, each carrying distinct information (bulk scope, confirmation workflow, rate-limit/failure behavior, note semantics) 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 bulk mutation with no output schema, it covers the critical operational facts an agent needs (confirmation, rate limit, partial failure, shared note). It leaves out the maxItems=200 bound and how failed items are reported, which would matter at the edges.

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 only 33% (only 'note' is described in the schema), so the description must compensate. It does clarify that all candidates share one 'stage' and one identical 'note', but it omits the 200-item cap and any stage-value semantics.

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

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

States a specific verb (move), resource (candidates), and scope (a list to the same stage in one go). The bulk scope unambiguously distinguishes it from the sibling move_candidate without needing to name it.

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?

Gives a concrete usage precondition: show the user the list and get explicit confirmation first. It does not name when to prefer the single-candidate move_candidate or when-not to use this, so it falls short of explicit 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?

Annotations already declare a non-destructive, open-world write, so the safety bar is lower. The description usefully adds the vacancy_id fallback behavior (general candidates pool), which is real context beyond the annotations. It does not cover required-field enforcement, side effects on other records, or what a successful call returns.

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 tight sentences, zero filler, and the primary action leads while the conditional detail follows. Efficient for the amount of content it chooses to deliver.

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 12-parameter mutation tool with 8% schema coverage and no output schema, the description is too thin. An agent cannot infer required fields, field formats, or the meaning of the majority of parameters from it, even though the vacancy_id behavior is well handled.

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 only 8% across 12 parameters, so the description carries almost the whole burden and does not meet it. It only clarifies vacancy_id, leaving first_name/last_name/email requirements, sourced, and the other eight fields undocumented. This is a clear compensation failure.

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 (create) and the actual resource ("a job application"), then grounds it with concrete examples (sourced on LinkedIn, met at an event). There is mild tension between the tool name "create_candidate" and the described resource "job application," but the description resolves it better than the title does. It does not explicitly distinguish itself from the other creation-adjacent siblings.

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 examples imply the sourcing use case, and the second sentence gives the key conditional (omitting vacancy_id routes the candidate to the general pool). However, it names no alternatives and states no when-not condition, so routing among update_candidate/add_note/upload_candidate_file is left 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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds meaningful context beyond them: the deletion is permanent/irreversible and demands explicit user confirmation, which raises the behavioral bar well above the annotations alone.

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 tight sentences with zero filler. The irreversible nature and confirmation requirement are front-loaded, so the most consequential information is read 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?

For a one-parameter destructive tool with no output schema and annotations covering the safety flags, the description supplies the key missing pieces: permanence and confirmation gating. Only minor gaps remain (no mention of cascade effects or what success looks like).

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

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

Schema description coverage is 0%, so the description is expected to carry parameter meaning, yet it says nothing about job_application_id. The single parameter is self-explanatory by name, limiting the damage, but no compensating detail (format, where the ID comes from) is offered.

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 ('Permanently delete') and resource ('a job application'), clarifying that the target is the job application rather than the candidate named in the tool. It doesn't explicitly differentiate from siblings like update_candidate or move_candidate, but the destructive intent is 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?

Provides a concrete precondition ('only call after explicit user confirmation') and a scenario that frames legitimate use ('GDPR erasure request'). It stops short of naming alternatives or when-not-to-use cases, so it lacks the full routing guidance 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that optional includes are available, but it does not explain what 'full details' entails, error behavior (e.g., missing ID), or any rate limits; with annotations, a 3 is appropriate.

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

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

The description is a single sentence with zero waste, front-loading the core purpose without extraneous detail. 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 simple tool with two parameters and no output schema, the description is mostly adequate. However, it could clarify what 'full details' includes or describe the return format, and it omits any mention of error handling or pagination.

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

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

Schema description coverage is 0%, so the description must compensate. It does mention the optional include values ('notes, sources and vacancy'), which map to the enum, and implies job_application_id via 'one candidate', but it does not explain the ID format or that include is an array. The description adds some value but leaves gaps.

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 specifies a clear verb ('Full details of') and resource ('one candidate'), making it distinct from list_job_applications. However, it does not explicitly differentiate itself from siblings like get_vacancy or list_job_applications, relying on the name for that distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives, nor on prerequisites or exclusions. The phrase 'optionally with notes, sources and vacancy' hints at usage but does not state when to include those extras or when to prefer a different sibling.

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 and openWorldHint, so the safety profile is covered. The description adds useful context about what payload is returned (description always, stages/candidate count optionally), but says nothing about auth needs or failure behavior for an unknown vacancy_id.

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?

A single efficient sentence that front-loads the core payload ('full details of one vacancy') before the optional expansions. No filler, though it could be slightly more precise about the include parameter.

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 lookup with no output schema, the description adequately conveys the return shape and the optional expansions. The main gap is that half the include enum values (location, department) are not surfaced anywhere.

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

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

Schema coverage is 50%: vacancy_id has an example description while the include enum items are undocumented in the schema. The description partially compensates by naming 'stages' and 'candidate count' as optional inclusions, but omits the 'location' and 'department' include values entirely.

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 ('Full details of one vacancy') and clarifies scope as a single record, which implicitly separates it from list_vacancies. It does not name the sibling alternative explicitly, so it stops short of 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?

Usage is implied by the parameter (fetch details for one vacancy by id) and by the sibling list_vacancies, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative.

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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is thin; the description compensates by disclosing the side effect (writing a file), the exact sheets produced for xlsx, and that returns data only for piping into another connector. It still omits permission/auth requirements and overwrite behavior for output_path.

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?

Front-loaded with the report's contents before the format mechanics; no filler sentences. The format explanation is dense but the long parenthetical with three format behaviors makes it slightly harder 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?

With no output schema, the description usefully describes what each format returns, so an agent knows what it gets back. A mutation-adjacent tool (writes a file, sets readOnlyHint=false) would benefit from naming permission or overwrite expectations, but coverage is otherwise solid for its 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 60%. The description adds real meaning for format (per-value output differences) and restates the reply_sla_days and vacancy-scope defaults, but leaves include_closed entirely undocumented in both schema and description, and says nothing about output_path semantics.

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

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

States a specific verb and resource ('Build a hiring report across all open vacancies') and enumerates the exact metrics produced: funnel per stage, hired, disqualified, average rating, time to first reply, and overdue candidates. This is well differentiated from siblings like pipeline_summary or list_job_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 explains what each format value does, which implies when to pick xlsx vs csv vs json, but it never contrasts this tool with candidates like pipeline_summary or says when not to use it. Usage is implied rather than stated.

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 openWorldHint=true, so the safety profile is covered. The description adds one meaningful behavioral detail beyond that: the call exercises authentication, so an agent knows a failure signals bad/missing credentials rather than a data error. It says nothing about latency, rate limits, or what a failure looks like.

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?

A single short sentence with the operative verb and object front-loaded and zero filler. Nothing could be trimmed without losing 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?

For a zero-parameter probe this is nearly complete: the agent knows what it does and that no arguments are required. Since there is no output schema, a brief note on what success/failure returns would be the only useful addition.

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, which is the baseline-4 case. The description correctly implies no input is needed, matching the empty schema, and nothing is missing or misleading.

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 action and object ('verify the API key works'), and combined with the title 'Check Homerun connection' an agent can tell this is a connectivity/auth probe rather than a data operation. It is clearly distinguishable from every sibling (list_vacancies, create_candidate, etc.), though the sentence itself does not name what makes it distinct.

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?

There is no explicit when-to-use guidance, no mention of when not to use it, and no alternatives offered. The implied use case (diagnosing whether credentials are valid before calling other tools) must be inferred by the agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds no behavioral context beyond filtering — no note on paging behavior, result ordering, or whether stage values must pre-exist on the vacancy, which is the one real trap here.

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?

One front-loaded sentence with zero filler: purpose first, then the three filter axes, with the multi-id hint parenthesized exactly where it matters.

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 list tool with no output schema, this covers the essentials: what is listed and how to narrow it. It falls slightly short on paging/return expectations and leaves the include parameter unexplained.

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?

Coverage is a middling 67%. The description usefully adds that vacancy ids may be comma-separated (the schema gives vacancy_id no description at all) and clarifies stage/hire-date filters. However, page, perPage, and especially the undescribed 'include' enum are left entirely to 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?

States a specific verb+resource ('List job applications (candidates)') and names the filter dimensions. It distinguishes itself from get_job_application by being plural/list-shaped, though it never explicitly contrasts with list_vacancies 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 filter clauses imply when to reach for this tool (browsing candidates by vacancy, stage, or hire date), but there is no explicit when-to-use or when-not-to-use guidance and no pointer to siblings like get_job_application for a single record or pipeline_summary for aggregates.

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 openWorldHint=true, so the safety profile is covered. The description adds that list results can be enriched with pipeline data, but says nothing about pagination behavior, default page size, or result scoping beyond what the schema shows.

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 short sentences with zero waste; the core action is front-loaded and the enrichment hint follows. Nothing redundant or padded.

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

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

Adequate for a read-only list tool with no output schema: the schema covers pagination defaults and limits. However, it never mentions the status filter's role (public/private/draft/closed) or that results are paged, leaving part of the tool's behavior to inference.

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

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

Schema coverage is 50%: page and perPage carry descriptions, while status and include are bare enums. The description partially compensates by explaining the purpose of two include values ('stages','total_candidate_count' → hiring pipeline), but status filtering and the 'location'/'department' include values remain uninterpreted.

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 ('List job openings (vacancies)'), immediately clear to an agent. It doesn't explicitly contrast with the singular sibling get_vacancy or with pipeline_summary, so it stops short of full 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?

Gives one concrete usage cue: pass include=['stages','total_candidate_count'] to see each job's hiring pipeline. There is no guidance on when to prefer this over get_vacancy, list_job_applications, or pipeline_summary, so usage is implied rather than stated.

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 non-read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds meaningful context the annotations can't convey: a hard restriction on 'New' and a required user-confirmation step before invocation. It omits side effects like notifications or what happens to prior stage history.

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, zero filler, with the disallowed case and the confirmation requirement front-loaded where an agent will see them.

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 mutation tool with annotations covering safety and no output schema, the description supplies the critical preconditions (valid stage, no 'New', user confirmation). The main residual gap is the undocumented job_application_id and the absence of any note on downstream effects.

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 only 33% — vacancy_id is documented but stage and job_application_id are bare. The description partially compensates by constraining stage ('must exist in the vacancy', cannot be 'New'), yet it never clarifies what job_application_id represents, leaving one required parameter unexplained in both places.

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 and resource ('Move a candidate to another existing stage of the hiring process'), so the agent knows exactly the operation and object. It implicitly distinguishes itself from bulk_move_candidates (singular vs. bulk) but never names or explicitly contrasts that sibling.

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?

Gives real usage conditions: the stage name must exist in the vacancy, moving back to 'New' is disallowed, and the user must be asked to confirm first. It stops short of routing to the sibling bulk_move_candidates for multi-candidate moves or explaining what to do when the target stage doesn't exist.

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: it aggregates across all pages automatically and warns about the 60 req/min limit, which signals cost and potential throttling. It stops short of stating whether results are live or fixed snapshots, which is the one gap on a tool literally named 'snapshot'.

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, densely packed with zero filler, and the returned metrics are front-loaded before the pagination and rate-limit note. Every clause 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?

With no output schema, the description correctly takes on the job of describing the return payload by enumerating the four metrics. Combined with the pagination and rate-limit note, an agent knows what it will get and what it will cost, leaving only minor gaps such as no explicit sibling disambiguation.

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

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

Schema description coverage is 0% for the single required parameter, so the description has to carry the burden. Saying 'one vacancy's funnel' does establish that vacancy_id selects a single vacancy and that the scope is the whole funnel, but it adds no format guidance (ID type, source, validity) beyond that implication.

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 names a specific resource (one vacancy's funnel) and enumerates exactly what the snapshot contains: candidates per stage, disqualified count, average rating, and candidates awaiting a first reply. That is far more informative than a restatement of the name, though it does not explicitly contrast itself with siblings like hiring_report or get_vacancy, which an agent might reasonably confuse it with.

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?

There is no explicit when-to-use guidance and no named alternative. The only conditional statement is a rate-limit caution, which is operational advice rather than usage routing. An agent must infer for itself when a funnel snapshot beats hiring_report or list_job_applications.

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=false, destructiveHint=false, and openWorldHint=true, so the mutation/safety profile is covered. The description adds only 'contact or profile fields', which the schema already implies, and omits partial-vs-replace semantics, auth requirements, and what happens to unspecified fields.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity comes at the cost of the detail the other dimensions lack.

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 mutation tool with no output schema, a nested 'fields' object, and a required-but-undocumented key parameter, the description is too thin. It should at least clarify the partial-update behavior of 'fields' and the role of job_application_id.

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

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

Schema coverage is 50%: the 'fields' object is documented in the schema but 'job_application_id' is not. The description adds nothing to either parameter — it never explains that job_application_id identifies which candidate is updated or how the fields map merges into the profile.

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 ('Update') and resource ('contact or profile fields of a candidate'), making the operation identifiable. It does not differentiate itself from siblings like create_candidate or delete_candidate, but no sibling overlaps the update operation, so the risk of confusion is low.

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 no when-to-use guidance, no prerequisites, and names no alternatives. An agent is left to infer that this is the tool for modifying an existing candidate versus create_candidate or move_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?

Annotations already declare this is a non-read-only, non-destructive write with open-world effects, so the safety profile is covered. The description adds that the file must be local (not a URL) and that the two accepted kinds are resume and assignment, but says nothing about overwriting existing files, size/format limits, or required 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?

One clean sentence with the key noun (local file) and accepted kinds front-loaded; nothing is redundant. It is arguably under-specified rather than overstated, but 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?

A three-parameter required mutation tool with no output schema and one-third schema coverage; the description does not clarify the job_application_id target, success/failure behavior, or limits on file type and size. An agent has enough to attempt the call but not enough to call it confidently.

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 only 33%: file_path is documented ('Absolute path on this computer') and the type enum is self-describing, but job_application_id is undocumented in both schema and description. The description's 'resume or assignment' wording mirrors the enum values but adds no real meaning, and it never explains that attachment targets a job application ID rather than a candidate.

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 and resource: attach a local file (resume or assignment) to a candidate. The tool's action is unambiguous, though it does not name or distinguish itself from plausible siblings like update_candidate or create_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 gives no when-to-use guidance, no prerequisites (e.g., the candidate/job application must already exist), and no alternatives. Usage is only loosely implied by the word 'Attach'.

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