Yardstick ATS

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

The description adds some traits beyond annotations, such as 'revocable' and 'audited,' but it does not explain operational behavior like whether the grant takes effect immediately, whether confirmation in Yardstick is required, or what permissions are needed. The title's parenthetical 'confirm in Yardstick' hints at an important confirmation step that the description fails to address.

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 tight sentence that front-loads the action and avoids filler. It is concise, though its brevity comes at the cost of operational detail.

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?

This is a complex create operation with 10 parameters, no output schema, and zero schema description coverage. A single abstract sentence does not give an agent enough context to choose required subjects, scopes, target IDs, artifact classes, or timing fields, let alone understand the confirmation behavior hinted at in the title.

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 the description names none of the 10 parameters. 'Reasoned' and 'revocable' only vaguely hint at `reason` and `revocable`, leaving the meaning of `subject_person_id`, `scope`, `target_id`, `artifact_classes`, `expires_at`, and others completely 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?

The description clearly states an active verb ('Create') and a concrete resource ('access grant'), and the title reinforces this as granting someone access to a record. It is distinguishable from the sibling list/read/revoke tools by action type, though it does not explicitly call out 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 guidance on when to use this tool versus alternatives, no mention of checking existing grants via list/read, and no note about using revoke for removal. For an access-control mutation, failing to mention prerequisites or alternatives leaves the agent to infer usage from the name alone.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping detail that only grants visible to the current principal are returned, but it does not mention pagination behavior or response shape, which would add value beyond 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 a single, front-loaded sentence with no filler. Every word contributes meaning, and the most important scoping information appears immediately.

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, the description gives the essential purpose and scope. However, with three pagination-related parameters and no explanation of how results are returned, the definition leaves an agent without enough information to confidently paginate or interpret the response.

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 needed to compensate for the three parameters (limit, request_id, starting_after). It does not mention that limit/starting_after are pagination controls or what request_id is for. The parameter names are suggestive but not documented, leaving agents to guess.

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 ('List'), a specific resource ('access grants'), and important scope qualifiers ('explicit', 'visible to the current principal'). This clearly distinguishes the list operation from the sibling read (single grant), create, and revoke 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 implies the tool is for enumerating the current principal's explicit grants, which provides clear context. However, it does not explicitly state when not to use it or name alternatives, though the sibling set makes the distinction fairly 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral nuance that the access grant ID is a 'public id,' but it does not clarify response format, error conditions, or any side effects. No contradiction with annotations 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?

The description is a single, tight sentence that leads with the verb and resource. Every word contributes value, and there is no fluff or repetition. For a simple read operation, this level of brevity is appropriate.

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, so the description should describe what the tool returns to be complete. It does not mention the response shape, whether the grant is returned in full or partial, or any error handling. An agent cannot fully anticipate the tool's outcome, making the definition incomplete for a read operation.

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 carries the burden of parameter explanation. It clarifies that access_grant_id is a public ID, but it says nothing about request_id, leaving its purpose ambiguous. The description only partially compensates for the complete lack of schema-level 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 immediately states the verb 'Read' and the resource 'explicit access grant' with the qualifier 'by public id,' which clearly specifies the operation. It is easily distinguished from siblings like yardstick_access_grants_list or yardstick_access_grants_create, which have different purposes.

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 explicit guidance on when to use this tool versus alternatives. It does not mention that list should be used to find grants by other criteria, or create/revoke for mutations. The implied use case is a single lookup, but there is no explicit when-to-use or exclusion information.

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 destructiveHint=true and readOnlyHint=false, indicating a mutation. However, the description does not disclose that this likely requires confirmation (as the title hints) or that the action is irreversible. The mention of 'confirm in Yardstick' in the title is undercut by the description's omission of any confirmation behavior or irreversible consequences. The description adds little 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 a single short sentence, which is efficient, but it fails to include critical information like the confirmation flow. The title duplicates information about confirmation, but the description itself is optimally concise for what it covers.

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 is a destructive mutation with no output schema and no parameter descriptions, the description is too sparse. It does not mention what happens to the grant, whether bind/preview pattern is needed (siblings have bind/preview patterns for destructive actions), or how to handle the optional parameters. The title hints at a confirmation step that the description omits.

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 0% (no descriptions in the schema), and the description only mentions 'optional reason text' but does not explain the purpose of 'request_id' or 'idempotency_key'. With 4 parameters and required 'access_grant_id', the description leaves the agent to guess the semantics of the optional parameters, especially 'idempotency_key', which implies retry behavior not mentioned.

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 clear verb ('Revoke') and direct object ('access grant'), and the title adds context about confirmation in Yardstick. It is distinct from siblings like 'yardstick_access_grants_create' and 'yardstick_access_grants_list'. The term 'explicit' avoids ambiguity with system grants, which is helpful.

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

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

The description implies this is used to revoke an access grant, but does not explicitly state when to use it versus alternatives (e.g., when you need to disable a grant vs. delete it). It does not provide conditions or exclusions, leaving some inference up to 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 flag idempotentHint=true, readOnlyHint=false, destructiveHint=false; the description is consistent and adds the end-state idea that a session will exist for the round. It does not state what happens when one already exists, whether it creates or reuses, what it returns, or any permission/rate-limit context, so credit is limited.

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 dense sentence with no filler and the key id (round) is front-loaded. It is concise to the point of under-specification, but as far as structure and length it 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, 0% parameter coverage, and no behavioral detail, this is too thin for reliable invocation. An agent cannot predict the return value, the effect on an existing session, or the role of the optional parameters, and there is no pointer to sibling tools.

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 descriptions cover 0% of six parameters, and the description only references round_id (and application_id by tool-name inference). Optional params like round_title, request_id, idempotency_key, and interview_plan_id get no explanation, so an agent cannot tell what values to supply.

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 title and description name a specific resource ('application interview session') and scope it to an explicit round id, with 'Ensure'/'Make sure an interview exists' conveying an idempotent create-if-missing intent. This is enough to distinguish it from list/read/cancel/start session tools, though 'Ensure' alone is slightly vague.

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?

No sentence tells an agent when to choose this over yardstick_application_interview_sessions_list or the interview_sessions_* lifecycle tools, and no exclusions or alternatives are named. The only implicit signal is the word 'Ensure', which is too weak to route reliably.

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, idempotentHint=true, and destructiveHint=false. The description adds no behavioral detail beyond the basic list operation, such as whether cancelled sessions are included, ordering, pagination, or output shape.

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 no filler, wasted words, or redundant restatement. It front-loads the action and scope efficiently.

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

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

The tool is simple, with one required parameter and annotations covering its safe read-only nature. However, with no output schema, the description could have added useful context about what the returned list contains or whether pagination is involved. It is minimally viable but not 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 0%, so the description needed to explain parameter semantics, but it only says 'for an application.' This weakly maps to application_id but says nothing about the optional request_id or the expected format or behavior of the parameters.

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

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

The description names a specific verb ('List'), a concrete resource ('interview sessions'), and a clear scope ('for an application'). This is enough to distinguish it from sibling session tools like interview_sessions_read or application_interview_sessions_ensure.

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 guidance about when to choose this tool over related alternatives, such as reading a single interview session or ensuring sessions exist. There is no stated context, exclusion, or alternative 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 declare destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. The description adds context about requiring 'explicit approval metadata' and 'matching idempotency key', which clarifies the safety contract. However, it doesn't disclose what gets archived, whether the application becomes inaccessible, or any side effects beyond archiving.

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 no filler, and the key constraint ('already-previewed') is front-loaded. It earns its place by conveying the essential precondition and the approval requirement.

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?

This is a destructive, idempotent bind operation with a nested binding object and 0% schema coverage, yet the description doesn't explain the preview-bind workflow, what the binding fields mean, or what happens after archiving. An agent would struggle to construct a valid 'binding' object without additional context.

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

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

Schema description coverage is 0%, so the description must compensate, but it only mentions 'approval metadata' and 'idempotency key' generically. It doesn't explain the nested 'binding' object's fields (preview_hash, approved_action_key, approved_input_hash, approved_idempotency_key, resource_version_precondition) or how they relate to a prior preview. The 'reason' and 'request_id' parameters are 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?

The description states a specific verb ('Bind') and resource ('already-previewed application archive') with explicit approval metadata and idempotency key. It distinguishes from preview tools by emphasizing 'already-previewed' and 'explicit approval metadata', though it doesn't name sibling alternatives directly.

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

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

The description implies this is the confirmation step after a preview, and the 'already-previewed' phrasing signals it should not be used before previewing. It doesn't explicitly name alternatives like yardstick_applications_archive_preview or transition_bind, but the context is clear enough for an agent to infer the preview-then-bind workflow.

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

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

The title and description explicitly claim no state change ('nothing changed yet,' 'Preview ... only'), but the annotations set readOnlyHint=false. This is an annotation contradiction. The description does add useful context about rejecting bind fields, but the conflicting readOnlyHint undermines the behavioral signal.

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, with the core purpose in the first clause. The second clause is terse but relevant. It wastes no words, though 'bind fields are rejected' could be clearer.

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

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

For a tool with no output schema and four undocumented parameters, the description is too thin. It does not describe what the approval requirements look like, how the response is structured, what makes a request valid, or how to act on the preview results. The non-mutating nature is clear, but substantial operational context 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 description coverage is 0%, and the description does not explain application_id, reason, request_id, or idempotency_key. The only parameter-related statement, 'bind fields are rejected,' is ambiguous about which fields those are and does not compensate for the complete lack of 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 action ('Preview') on a specific resource ('application archive approval requirements') and limits scope with 'only.' The title reinforces the non-mutating nature with 'nothing changed yet,' and the warning that 'bind fields are rejected' helps distinguish this from the archive_bind 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?

The phrase 'Preview ... only' and 'bind fields are rejected' clearly tells an agent this is not the tool for actually performing the archive bind. However, it does not explicitly name the alternative or say 'use this before yardstick_applications_archive_bind,' so the when-to-use guidance is mostly implied rather than fully explicit.

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 annotations already indicating a non-read-only, non-destructive mutation and no idempotency, the description adds the prerequisite that the person and job posting must already exist. It stops short of explaining side effects, idempotency_key behavior, or what happens on duplicate creation, but the annotation baseline lowers the burden.

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 sentence that front-loads the action and packs the key qualifiers (source type and existence requirement) without filler. Every phrase contributes to selection and invocation.

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 flat four-parameter create operation, the description is minimally sufficient: it names the core entities and the required preconditions while annotations cover the mutation safety profile. The optional request_id/idempotency_key semantics and any post-create behavior remain unaddressed, leaving a clear but not fatal gap.

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 has to compensate for parameter meaning. It semantically covers person_id and job_posting_id via 'existing person and job posting,' but it says nothing about request_id or idempotency_key, leaving two of four parameters effectively 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?

The description uses a specific verb ('Create') and resource ('application'), and narrows the action with 'recruiter or agent-sourced' and 'for an existing person and job posting.' This distinguishes it from sibling operations like update, transition, and archive without needing to introspect their schemas.

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 'for an existing person and job posting' gives a clear prerequisite and context for when to call this tool, and the create stance implies it is for adding rather than updating/transitioning. It does not, however, name alternatives or explicitly state when not to use it.

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 idempotentHint=true, so the description doesn't need to repeat those. The description adds 'with idempotency metadata', which aligns with the idempotentHint and hints at the idempotency_key parameter. However, it doesn't disclose side effects (e.g., that it changes the application status and may send an email) or any prerequisites. The title partially covers this ('Apply a status change and its candidate email'), but the description itself adds minimal behavioral context beyond what annotations provide.

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

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

The description is a single, concise sentence that front-loads the primary action ('Apply') and the object ('an application status-change email decision'). It is not verbose and contains no filler. Despite being under-specified, this dimension only measures conciseness and structure, and the description is exemplary in that regard.

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 operation with three parameters, no output schema, and zero schema descriptions, this description is severely incomplete. It does not explain what an 'email decision' is, how to obtain one, what happens when applied (e.g., status change and email sending), or the role of idempotency_key. An agent cannot safely invoke this tool without additional information, making it inadequate for its context.

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

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

Schema description coverage is 0%, so the description must explain parameter meanings. It only mentions 'idempotency metadata' without specifying which parameter is the idempotency key. It does not explain request_id, application_id, or idempotency_key semantics, nor does it indicate that application_id is required. The description fails to compensate for the lack of schema descriptions, leaving an agent guessing about parameter usage.

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 clear action ('Apply') on a specific resource ('an application status-change email decision') and mentions idempotency metadata. It distinguishes from preview tools (e.g., email_decision_preview) by indicating this is the apply step, and from transition_direct by referencing an 'email decision' rather than a raw transition. However, it doesn't explicitly clarify what constitutes an 'email decision' or how it differs from the related status_email_poc_bind, leaving some ambiguity.

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?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention that a decision should first be previewed (e.g., via email_decision_preview) before applying, nor does it state that this tool is the final step after previewing. There are no exclusions or conditions. An agent would not know if this is the right tool without further context.

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

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

The description explicitly guarantees no mutation of the application or drafts, which is valuable because the annotation readOnlyHint is false)Skip this valuable context is not carried by annotations. It also reinforces the idempotent and non-destructive nature already hinted at by idempotentHint and destructiveHint. No contradictions 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 a single sentence, concise and front-loaded with the action 'Preview'. It avoids redundancy and effectively clarifies the non-mutating behavior. It could be slightly more structured, but there is no unnecessary content.

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

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

Given there is no output schema, the description should explain what the preview returns (e.g., email subject, body, recipient) but does not. It also leaves parameter semantics unexplained. While the tool is simple and the required application_id is implied, an agent cannot know the exact request construction or response format, making the description insufficient for correct invocation without additional context.

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

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

The description provides zero information about the parameters. Schema description coverage is 0%, so the description must compensate, but it mentions neither application_id nor the optional request_id and idempotency_key. The only hint is the word 'application' in the tool name, which is not enough to clarify parameter semantics. There is no added meaning beyond the schema's structural definitions.

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 previews the candidate email for an application status change alerting the agent to the fact that nothing is sent. It explicitly says it does not mutate the application or drafts, which distinguishes it from the sibling 'yardstick_applications_email_decision_apply' and related transition tools. The verb 'Preview' and the resource (candidate email for application status change) are specific and unambiguous.

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

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

The phrase 'without mutating the application or drafts' implicitly conveys that this is for previewing before applying a change rather than executing it. However, it does not explicitly name alternatives like yardstick_applications_email_decision_apply or yardstick_applications_transition_preview, nor does it state when to use this tool versus those siblings. The context is clear enough for a knowledgeable agent but lacks explicit 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the scoping constraint 'visible to the current principal,' which is useful context beyond annotations. However, it omits other behavioral details like pagination behavior, ordering, or default limits, so it only partially supplements 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 a single concise sentence with no extraneous words. It is appropriately short, though it sacrifices necessary detail for brevity. The structure is simple and readable, earning a high score on conciseness despite the lack of depth.

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 list operation with three pagination parameters and no output schema, the description is severely incomplete. It does not describe what is returned, how pagination works, or any default behavior. An agent would lack essential information to invoke the tool correctly, especially given the ambiguous resource description.

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

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

Schema description coverage is 0%, and the description does not explain any of the three parameters (limit, request_id, starting_after). Since the schema itself provides no descriptions, the description carries the full burden but fails to clarify parameter meanings, making it nearly impossible to use correctly.

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 clear verb ('List') and a resource ('application person + Job attachments'), but the resource is ambiguous and poorly worded. It does not distinguish this tool from other list operations in the sibling set, such as yardstick_opportunities_list or yardstick_people_list, and the phrase 'application person + Job attachments' is confusing.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of conditions, exclusions, or comparison to related tools like yardstick_applications_read or other list tools. An agent would have no help deciding which list tool fits a given need.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it reads by 'public id' and includes 'person + Job attachment', offering some content context but not detailing behavior on missing IDs or data format. This is modest added value beyond 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?

One sentence with no filler, but the compressed phrase 'person + Job attachment' sacrifices clarity. It is concise but somewhat ambiguous, so it doesn't fully earn its place as clear guidance.

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 two parameters, no output schema, and no nested objects, the description should still explain the unusual 'person + Job attachment' term and the optional request_id. It does neither, leaving agents uncertain about the exact call shape and return semantics.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meanings. It implicitly maps 'public id' to application_id, but request_id is completely unmentioned. This is partial compensation at best and leaves a required-parameter gap for agents.

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 read operation on an 'application' by public id. The phrase 'person + Job attachment' is ambiguous but still points to a specific resource type. The singular 'one' and 'by public id' help distinguish it from list operations, though it doesn't explicitly name 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?

There is no guidance on when to use this tool instead of alternatives like yardstick_applications_list or other read tools. It doesn't describe ideal use cases, prerequisites, or exclusions, leaving the selection decision 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 idempotentHint=true, so the description does not need to restate those. It does add useful operational context by saying the call requires 'explicit approval metadata and a matching idempotency key,' which clarifies that this is an approved, replay-safe bind. However, it does not disclose the concrete consequences—status mutation and an outgoing candidate email—beyond what the title and annotations imply.

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 no filler, so it is concise. However, the phrase 'fixed applications-owned status/email approval POC' is dense and confusing, and the sentence does not lead with an approachable outcome. Brevity comes at the expense of clarity.

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?

This is a destructive 11-parameter bind operation with a nested binding object, no output schema, and no parameter descriptions, yet the description omits the key workflow prerequisite: running a preview first to obtain the approval metadata. It also gives no hint about where binding values come from or what a successful call returns. The schema constants constrain some inputs, but the overall workflow context is still 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 description coverage is 0%, so the description had to compensate by explaining the parameters. It adds a little meaning by grouping the nested binding fields as 'explicit approval metadata' and by saying the idempotency key must match. But it leaves preview_hash, approved_action_key, approved_input_hash, and resource_version_precondition completely unexplained, so an agent still cannot determine what values to supply or where they come from.

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 ('bind') and names a specific resource ('applications-owned status/email approval POC'), so it is not a tautology. However, the wording is jargon-heavy and fails to state the real-world effect that the title conveys: confirming the Offer status change and sending the candidate email. An agent would need to infer the apply-after-preview workflow from sibling-naming conventions rather than from the description itself.

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 guidance about when to call this tool versus the many sibling bind/preview/transition tools. It does not mention that a preview should precede this bind, nor does it say not to use yardstick_applications_transition_bind for this workflow. Without that context, an agent cannot reliably choose this tool.

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

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

The description claims the tool mutates nothing ('without mutating status or email state'), but the annotations set readOnlyHint=false, which indicates the tool is not read-only. This is a direct contradiction, and per the rubric behavioral transparency must be scored 1 with an annotation contradiction flag.

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 that front-loads the core purpose and the safety guarantee. There is no filler or repetition beyond the title, and every phrase adds relevant 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?

This is a complex 10-parameter tool with no output schema and no parameter descriptions, yet the description only states that it is a non-mutating preview. It does not explain the expected preview output, how the parameters shape the preview, or what follow-up tool should be used to actually apply the change.

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 the description provides almost no parameter-level semantics beyond naming the statuses 'Interviewing' and 'Offer' and the concept of email. With 10 parameters and 5 required ones, the description fails to compensate for the absent schema 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 clearly states a specific action—'Preview'—and a specific resource: the applications-owned Interviewing-to-Offer status/email approval POC. It distinguishes from mutating sibling tools by saying it operates 'without mutating status or email state,' though it does not name a specific alternative.

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

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

The description implies a preview-before-apply workflow but gives no explicit when-to-use guidance, prerequisites, or mention of the sibling apply/bind tools as alternatives. An agent must infer that this is the safe preview counterpart to a mutating operation.

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 destructive and idempotent behavior)Skip. The description adds that the action requires 'explicit approval metadata' and a 'matching idempotency key', which are meaningful behavioral guardrails beyond the annotations. It also clarifies this is the bind step, not a fresh transition.

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 sentence, front-loaded with the verb and resource, and it immediately conveys the key precondition ('already-previewed') and the two essential concepts (approval metadata, idempotency key). No wasted words.

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

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

The tool is complex (nested binding object, 5 required fields, no output schema, no parameter descriptions). The description does not explain how to obtain the binding values or what the response looks like. An agent cannot reliably call this tool without additional documentation or sibling tool descriptions.

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 carries the burden of explaining parameters. It mentions 'approval metadata' and 'idempotency key' but fails to explain the binding object fields (preview_hash, approved_action_key, etc.) or their relationship to a preview. This leaves the agent unable to correctly populate the 7 parameters.

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

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

The description clearly states a specific verb ('Bind') and resource ('application transition'), and scopes it to 'already-previewed' transitions. This distinguishes it from preview tools and from the direct transition tool, even without naming 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 description implies this tool is used after a preview has occurred ('already-previewed'), but it does not explicitly instruct the agent to call the preview tool first, nor does it mention when to use this instead of the direct transition tool. Context is present but exclusions are not 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 destructiveHint=true and idempotentHint=true, so the description adds value beyond them: it discloses that only non-terminal transitions are permitted, that approval-only statuses are rejected outright, and that pipeline_stage_id resolves to a stage which is reported back in the response. No contradiction with annotations; the write behavior aligns with readOnlyHint=false.

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 filler. The core constraint (direct, non-terminal, approval rejected) is front-loaded, and the optional pipeline_stage_id behavior is packed efficiently into the second 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?

For a 6-parameter mutation tool with no output schema, the description covers the central decision (which transitions are allowed) and the key optional parameter's effect. However, it does not explain what 'non-terminal' means in practical terms, nor the role of idempotency_key/request_id, and it relies on sibling naming for the approval-flow contrast.

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 carries the full burden for parameter meaning. It adds context only for pipeline_stage_id (targets a configured stage, resolved stage reported back). The required parameters application_id and status, plus reason, request_id, and idempotency_key, receive no semantic guidance beyond the raw schema.

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

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

The description states a specific action ('Directly write') on a specific resource ('non-terminal application transition') and clarifies scope by noting approval-only statuses are rejected. It distinguishes itself from the transition_bind/transition_preview siblings via the word 'Directly' and the approval rejection clause, though it doesn't name the alternatives explicitly.

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 rejection of approval-only statuses implies when NOT to use this tool, and the sibling set (transition_bind, transition_preview) suggests the alternative path, but this is left to inference. No explicit 'use X instead when approval is required' guidance is given.

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 and title ('Preview', 'nothing changed yet') clearly indicate a non-mutating preview operation, but the annotation readOnlyHint=false suggests the tool may modify state. This is a direct contradiction. Since annotations are meant to guide the agent on side effects, the mismatch is critical and the description provides no clarifying behavioral details (e.g., auth requirements, rate limits, what is computed in the preview).

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 with no redundant words. It front-loads the key constraint (approval-required only) and rejection of bind/direct targets, then adds the optional pipeline_stage_id detail. The structure is efficient, though the second sentence is slightly dense and could benefit from clearer separation.

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

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

The tool has 7 parametershol, no output schema, and conflicting annotations. The description covers some scope restrictions but does not explain what the preview returns, the meaning of the other parameters, or any behavioral context (e.g., whether a preview has side effects, side-effects/approval flow, auth needs). It is insufficient for an agent to call this tool confidently beyond the basic restriction checks.

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?

With 0% schema description coverage, the description must compensate for the 7 parameters. It only adds meaning for pipeline_stage_id (mentions targeting a configured stage and status match) and implicitly touches status. The other parameters (reason, request_id, idempotency_key, employment_start_date, application_id) are not explained at all beyond the raw schema types and constraints, leaving the agent to guess their role in a preview context.

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 ('Preview'), a resource ('application transitions'), and a clear scope ('approval-required only'). It explicitly rejects bind fields and direct-write targets, which distinguishes it from the sibling tools 'yardstick_applications_transition_bind' and 'yardstick_applications_transition_direct'. The title reinforces that nothing changes yet, making the tool's role unambiguous.

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

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

The description says the tool is for approval-required transitions only and that bind/direct targets are rejected, which gives a clear when-not-to-use condition. It also specifies when to optionally provide pipeline_stage_id and the status constraint. However, it does not explicitly name the alternative tools (e.g., transition_bind, transition_direct) for cases that need binding or direct writes, leaving some inference to 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 provide readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the safety/mutation profile is established. The description adds a modest behavioral boundary by saying updates are limited to 'schema-bound public API fields', but it does not explain what destructive consequences may occur, how idempotency is implemented, or whether updates are partial or full replacements. It does not contradict 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 a single sentence with no filler, front-loading the action and target. However, the phrase 'schema-bound public API fields' is jargon-heavy and somewhat opaque, which slightly reduces clarity even though the structure is compact.

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 four parameters, no output schema, and no parameter descriptions, this tool needs more context to be safely invoked. The description fails to mention the meaning of idempotency_key, the specific fields that can be updated, prerequisites, or the nature of destructive behavior. Annotations help but do not fill the gap.

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 the description does not compensate by explaining stage, request_id, application_id, or idempotency_key. Saying 'schema-bound public API fields' gives no per-parameter meaning, allowed values, or format hints. The agent is left entirely dependent on parameter names, which are insufficient for correct invocation.

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 ('Update') and resource ('one application'), making the core operation clear. The phrase 'schema-bound public API fields' adds some scope but does not explicitly differentiate this from the many application-related sibling operations such as transitions, archive binds, or email decision applies. It is understandable, but not fully distinguished from sibling tools.

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

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

There is no guidance about when to use this tool versus alternatives like applications_transition_direct, applications_archive_bind, or applications_email_decision_apply. An agent is not told which update scenarios belong here and which belong to a sibling, so it must infer the boundary from the name alone.

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 annotations, the description explicitly discloses what the tool creates (people, jobs, interview plans as stubs, job postings, applications), that it replays idempotently, and what it never does (send outreach, merge people, delete records). This gives the agent a concrete side-effect model 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?

Two sentences with no filler: the first front-loads the action and its governing condition, the second compactly lists created and excluded behaviors. 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?

For a mutating apply tool with no output schema, the description covers the purpose, side effects, idempotency, and safety exclusions well. It falls slightly short on explicit parameter guidance for request_id and idempotency_key, and it does not name the dry-run predecessor by tool name, but an agent can still correctly invoke it with the required fields.

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?

With 0% schema description coverage, the description must explain the parameters, but it only meaningfully clarifies preview_hash ('matching the stored dry-run'). It does not explain import_id, request_id, or idempotency_key, even though idempotent replay is mentioned and idempotency_key is likely relevant to that behavior. The description leaves most parameter semantics to inference.

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 ('Apply') and resource ('ATS import preview'), includes the key condition (preview_hash matching the stored dry-run), and enumerates the entity types created. This clearly distinguishes it from sibling tools like yardstick_ats_imports_dry_run, yardstick_ats_imports_read, and yardstick_prospect_imports_apply.

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 usage context clear: apply only an approved ATS import preview whose preview_hash matches the stored dry-run. It implicitly routes the agent toward the dry-run-then-apply workflow and away from read-only or preview-only tools, though it does not explicitly name alternatives or give when-not conditions.

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

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

The description asserts a dry-run behavior with 'Preview', 'no records written' in the title, and 'no application conversion side effects.' This directly contradicts the annotation readOnlyHint: false, which signals the tool may not be read-only. Because the description conflicts with the provided annotation, the score must be 1 per the rubric. The extra detail about JSON-only input and low-confidence match handling would otherwise be valuable behavioral disclosure, but the contradiction undermines trust.

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 dense sentence with no filler. It front-loads the primary purpose and packs the key constraints (JSON only, no raw file reads, no conversion side effects, explicit apply decisions for low-confidence matches). A more structured layout could improve scannability, but the content is tight and every clause adds 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?

This is a complex tool with 9 parameters, nested arrays, and no output schema. The description does not explain what the preview returns (e.g., validation errors, match summaries, or confirmation), nor does it clarify which parameters are typically required despite none being marked required. It also gives no usage examples or guidance on constructing the import payload. The description is incomplete for safe and correct invocation of such a multifaceted dry-run import tool.

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

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

Schema description coverage is 0% and there are 9 parameters, so the description must compensate. It only mentions 'source_kind: csv' and 'JSON rows only,' giving a hint about source_kind and input format, but it does not explain the meaning or relationships of jobs, candidates, applications, metadata, request_id, session_id, source_label, or idempotency_key. The description names the main resource categories but leaves most parameter semantics to the schema, which is insufficient at this parameter count and coverage level.

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: 'Preview a structured-row ATS import of candidates, jobs, and applications.' It clearly scopes the tool to CSV-style structured rows and distinguishes it from related apply/read tools by emphasizing 'preview', 'dry run' in the name, and 'no application conversion side effects.' An agent can tell this apart from yardstick_ats_imports_apply and yardstick_ats_imports_read without deeper 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?

The description provides clear context for when to use this tool: before applying an import, with JSON rows only, and when avoiding side effects or raw CSV/archive reads. It does not explicitly name the alternative apply tool or state 'use this instead of apply when you only want validation,' but the constraints strongly imply a dry-run workflow. The absence of explicit 'when not to use' wording keeps this at a 4 rather than 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the batch and its rows are returned and lookup is by public id, but no further behavioral context (pagination, permissions, error cases) is disclosed.

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

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

One sentence, front-loaded with the action and resource, with no filler, tautology, or redundant restatement of the title. 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 read tool, the core call (import_id by public id, returning batch and rows) is stated. However, with no output schema and no parameter documentation, request_id's purpose and the relationship between dry-run and apply batches remain unclear, making the description minimally adequate.

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 0%, so the description must compensate. 'By public id' clarifies that import_id is the batch's public identifier, but request_id is left completely unexplained and there is no hint about when it is needed.

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 ('Read'), names the resource ('ATS import dry-run/apply batch'), and states the payload scope ('and its rows'). This clearly distinguishes it from sibling operations like yardstick_ats_imports_apply and yardstick_ats_imports_dry_run.

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?

No explicit when-to-use or alternative routing is given. The read semantics imply it should be used to inspect a previously created dry-run/apply batch, but the description does not name apply/dry_run or explain when this read is preferable to other tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the visibility scoping ('public' and 'visible to the current principal') but does not disclose pagination, ordering, or other runtime behavior.

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

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

The description is a single clear sentence with no filler. It front-loads the action and resource, then adds the scopeful visibility qualifier.

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 and no parameter semantics in the description, the agent is left without important details such as response shape, pagination behavior, or how request_id and starting_after interact. The annotations cover safety but not the operational details needed for a correct call.

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 the description adds no meaning for limit, request_id, or starting_after. An agent must guess that starting_after is a pagination cursor and request_id is an identifier filter purely from parameter names.

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 (List), a specific resource (Yardstick audit log entries), and a scope qualifier (public entries visible to the current principal). This clearly distinguishes it from the many other list tools among the 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 description implies the tool is for viewing audit log entries, but it gives no explicit guidance on when to prefer it over alternatives or when not to use it. The 'visible to the current principal' qualifier provides some access context, but no conditions, exclusions, or sibling comparisons.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false, which is limited. The description adds valuable behavioral context by disclosing that the created rule is inert and fires no side effect, a nontrivial trait for an agent weighing whether calling this tool will have immediate external consequences. It does not disclose response format or validation behavior, but the key behavioral caveat is present.

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, well-structured sentence that front-loads the primary purpose, then gives the action palette, and ends with the important 'Inert' caveat. There is no redundant text; every clause contributes meaning.

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?

This is a create operation with a complex nested discriminated union and eight parameters, and no output schema. The description covers only the core trigger/action concept and the inert behavior. It does not explain that pipeline_stage_id is required, the meaning of position or condition, the is_active default, or how idempotency_key/request_id factor into the call, leaving an agent with significant gaps for a correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It names the three action palette options and mentions the trigger, covering two of the eight parameters. However, it leaves pipeline_stage_id, position, condition, is_active, request_id, and idempotency_key unexplained, and the agent would need to infer their meaning purely from the schema names and types.

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 'Create a stage automation rule', a specific verb+resource combination. It further clarifies the rule is composed of a trigger plus one of exactly three typed actions (send_scheduling_link / create_task / send_email), which distinguishes it from the sibling preview/update/read tools without opening their schemas.

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 tool's purpose makes the primary usage context clear — it is for creating automation rules. However, the description does not explicitly say when to prefer create over preview or update, nor does it note that preview may be used to test a rule before creation. The 'Inert — fires no side effect' note hints at a distinction from actually triggering the automation, but this guidance 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 destructiveHint=true and readOnlyHint=false. The description adds value by explaining that it is a plain delete with no approval step and that rules are inert config, so deleting unfired config has no candidate movement. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences: the first states the core action, the second adds critical behavioral nuance. It is front-loaded, dense, and contains no filler. 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 delete tool with two parameters, the description covers the purpose and the safety aspect (no candidates moved for unfired config). However, it lacks parameter explanations, particularly request_id, and does not mention idempotency or error behavior, leaving the definition incomplete for a tool with zero schema descriptions and no output 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 0%, so the description must compensate for parameter meaning. It does not mention rule_id or request_id at all. While rule_id is inferable from the resource name, request_id remains completely unexplained, leaving a significant gap for agents selecting or invoking the tool.

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 and resource: 'Delete a stage automation rule.' It distinguishes from sibling tools by explicitly noting 'Plain delete (no approval preview→bind)', separating it from the preview/bind pattern used elsewhere in the toolset.

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 context on when this tool is appropriate: it is the direct delete without an approval preview→bind flow, and it notes that rules are inert config so deleting unfired config moves no candidates. However, it does not explicitly mention alternatives or exclusions, like whether to use a different tool if you need to preview consequences.

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 the call as read-only, idempotent, and non-destructive; the description adds a useful behavioral model by explaining rules are inert config and that authoring does not fire side effects while an executor child runs rules later. This goes beyond the structured hints without contradicting them.

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

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

Two short sentences, front-loaded with the primary action and followed by the one behavioral clarification that matters. No redundant prose or repetition of the title.

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 annotated list call, the description is nearly complete: it covers what is listed, at what scope, and the side-effect model. There is no output schema, so the return shape is left implicit, and pagination/filtering is not mentioned, but the single optional parameter and read-only annotations make these minor gaps.

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 the description does not explain the sole request_id parameter, so no extra meaning is added beyond the raw schema. The impact is modest because request_id is optional and self-describing as a request identifier, but the low-coverage rule is not satisfied.

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 verb and resource ('List ... stage automation rules') and scopes it to the organization, so an agent can tell that this enumerates rules rather than reading, creating, or previewing them. It does not explicitly contrast with sibling automation-rule tools, so it stops short of the strongest 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 inert-config clause implies this is the safe inspection path and that execution happens later through an executor child, but it never states when to choose this tool over automation_rules_read, preview, or runs_list. The usage guidance is therefore implied rather than explicit.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explicitly states the tool 'mints no scheduling link, creates no task, sends no email; executes nothing.' This is exactly the kind of behavioral disclosure that helps an agent trust the tool is safe. It doesn't describe the return format, but with no output schema and annotations covering safety, the description does a solid job.

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 with zero waste. The first sentence states the purpose and the second sentence lists the non-effects. The 'INERT' emphasis is front-loaded and the safety guarantees are stated explicitly. 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 preview/dry-run tool with strong annotations (readOnlyHint, idempotentHint, destructiveHint all set), the description is nearly complete. It explains what the tool does, what it doesn't do, and the scenario it applies to. The only gap is that it doesn't describe what the response contains (resolved action params are mentioned but not detailed), and it doesn't explain the trigger parameter's two enum values. Given the tool's simplicity and annotation coverage, this is a minor gap.

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 carries the burden for parameter meaning. The description mentions 'a sample application entering/leaving a stage' which maps to application_id, trigger, and pipeline_stage_id. However, it doesn't explain the trigger enum values (stage_enter vs stage_exit) or the optional request_id and idempotency_key parameters. The description adds some meaning but doesn't fully compensate for the 0% 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 states a specific verb ('preview'), a specific resource ('automation rules'), and the exact scenario ('a sample application entering/leaving a stage'). The title reinforces this with 'runs nothing'. This clearly distinguishes it from sibling tools like yardstick_automation_rules_list (which lists rules) and yardstick_automation_runs_list (which lists actual runs).

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 clearly implies when to use this tool: when you want to know which automations would fire for a stage change without actually triggering them. The 'INERT' emphasis and 'executes nothing' clarify it's a dry-run alternative to actually applying a stage change. However, it doesn't explicitly name sibling alternatives like yardstick_applications_transition_preview or yardstick_applications_transition_direct, so it gets a 4 rather than 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 establish read-only, idempotent, non-destructive behavior. The description adds useful detail by listing what the response contains (trigger, typed action, target stage, is_active state), which helps the agent understand what this read operation 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?

The description is one concise sentence, front-loads the action and key identifier, and includes a compact parenthetical listing of returned fields. No redundant or filler text 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 simple read operation with no output schema, the description adequately states what is returned and how the rule is identified. The only notable omission is the optional request_id parameter, which is not necessary for a successful basic call.

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 description clarifies that rule_id is a public ID, adding meaning to the bare schema field. However, the optional request_id parameter is not mentioned anywhere, and schema description coverage is 0%, leaving that parameter 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?

The description clearly states the operation: 'Read one stage automation rule by public id' and enumerates the specific fields returned. It distinguishes this read tool from list/create/update/delete siblings by emphasizing singular retrieval by 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 makes the usage context clear: use this tool when you need a single automation rule by public ID. It does not explicitly name alternatives or state when not to use it, but the singular 'Read one' plus the tool name provide adequate differentiation from list-based 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 that this is a destructive, non-read-only, idempotent operation. The description adds no behavioral context beyond the annotation: it does not mention partial-update semantics (e.g., omitted fields remain unchanged), side effects, or required permissions. This leaves the agent to infer behavior from the schema and 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?

The description is a single sentence that is direct and free of filler. It front-loads the verb and resource, then lists the editable fields in a compact list. Nothing extraneous is included.

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?

This is a complex tool with eight parameters, nested action objects, enum values, and no output schema, yet the description provides only a terse list of editable fields. It omits critical context such as how to construct the action object, what a typical edit request looks like, partial-update behavior, and any relation to the rule's position or activation state. An agent given just this description would struggle to invoke the tool correctly.

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

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

With 0% schema description coverage, the description is the primary source of parameter meaning, but it only names the editable fields without explaining their semantics. For instance, 'typed action' is ambiguous—the schema defines three action object variants, but the description does not clarify which types are valid, what fields are required, or how 'condition' and 'position' behave. The description insufficiently compensates for the lack of schema parameter descriptions.

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

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

The description uses a specific verb ('Edit') and resource ('stage automation rule') and explicitly lists the editable attributes (trigger, typed action, condition, position, is_active state). This clearly differentiates it from sibling tools like create, delete, read, and list, so an agent can identify the correct operation without opening the schema.

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 verb 'Edit' implies this tool is used to modify an existing stage automation rule, but the description provides no explicit guidance on when to choose it over alternatives such as yardstick_automation_rules_create or yardstick_automation_rules_read. The usage context is implied rather than stated, and there are no exclusionary notes.

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, idempotentHint, and destructiveHint, so the description adds contextual value beyond them by explaining that runs are system-written by the executor and that skipped send_email rows are included for full observability. This is useful behavioral detail 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 a single well-structured sentence that front-loads the core purpose, then adds filtering, read-only status, and a behavioral nuance. Every clause contributes meaning, though a touch more structure could make the parameter list clearer.

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 list operation with no output schema, the description conveys what data is returned (which candidate, success/failure) and covers the inclusion of skipped rows DNA. However, it doesn't describe the response structure and leaves the request_id filter unexplained, making the definition adequate but not fully complete for an agent.

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

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

Since schema description coverage is 0%, the description carries the burden of explaining parameters. It names application-id and rule-id as filters, but completely ignores the request_id parameter and provides no type, format, or meaning for any of them. This leaves an important gap for an agent needing to construct a correct call.

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 ('List') and a distinct resource ('stage automation runs') while adding context about what the runs contain and how they are produced. This clearly distinguishes it from sibling tools like yardstick_automation_rules_list, which deal with rules rather than run history.

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 identifies two filters (application-id, rule-id) and notes the read-only nature, implying when this tool is appropriate for inspecting run history. However, it doesn't explicitly contrast with sibling tools or state when not to use it, and the request_id filter is omitted from the 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 mark the tool as destructive and idempotent, and the description goes beyond them by scoping the write ('only the built-in agent's declared settings keys') and adding the audit-row side effect. It does not detail auth or reversibility, but the main behavioral risk is addressed.

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, front-loaded with the verb and object, no filler. Each sentence adds distinct information: what is bound and what side effects occur.

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 bind tool with no output schema, the description conveys the core workflow pieces: an approved preview, matching config, approval metadata, and idempotency. It does not explicitly name configure_preview as the prerequisite step, but the approved-preview language makes the dependency clear enough.

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?

With 0% schema description coverage, the description adds needed meaning: config must be the same as the preview, binding carries approval metadata, and the idempotency key must match. It does not explain request_id or every binding subfield, but those are sufficiently self-describing in the schema.

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

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

The description names a specific action ('Bind'), a specific resource ('approved built-in-agent configure preview'), and states the effect: writes only declared settings keys and an audit row. This clearly differentiates it from the sibling configure_preview (which stages but does not save) and from enable_bind.

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 'approved built-in-agent configure preview' implies this is the commit step after a preview, but the description never explicitly says to use it after configure_preview or contrasts it with that sibling. Usage context is inferable, not 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?

The description explicitly claims 'Side-effect free', but the annotations declare readOnlyHint=false, which signals the tool may modify state. This is a direct contradiction between the description and the annotations, making it unsafe for an agent to rely on the stated side-effect behavior.

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

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

The description is a single dense sentence with no filler. Purpose, validation behavior, the key 'enabled' semantics, side-effect safety, and invocation method are all front-loaded and useful.

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

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

The core usage is covered well, especially the config semantics and side-effect-free guarantee. But there is no output schema and the description never explains what the preview returns or how the agent should interpret the response, leaving a meaningful gap for a tool whose whole purpose is to produce a preview.

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?

With 0% schema description coverage, the description adds real meaning to the config parameter: it is validated against the agent's declared schema, enabled is a first-class key, and { enabled: false } is the off switch. However, request_id and idempotency_key remain completely undocumented, and built_in_agent_id is only implied by the tool name.

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 says it previews configuring a built-in agent, names the resource, and emphasizes that nothing is changed yet. This makes the dry-run nature obvious and distinguishes it from the applying sibling (configure_bind).

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 context: use this to preview and validate config before applying, with no side effects, and pass config via --body-json. It does not explicitly name the apply alternative 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?

Annotations already signal non-readOnly and destructive behavior, and the description adds concrete side effects: it 'writes the built-in agent's declared settings home' and 'records one audit row.' It also reinforces the idempotentHint by requiring a matching idempotency key. 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?

Two sentences carry the action and the consequence with no filler. The primary action is front-loaded, and the audit/settings side effect is stated compactly in the second 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?

For a complex bind operation with a 5-field nested approval object and no output schema, the description is too thin. It does not indicate where the approval metadata comes from, what a successful response looks like, or how the binding relates to the enable_preview sibling, leaving a significant inference burden on the 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 description coverage is 0%, and the description only vaguely references 'explicit approval metadata' and a 'matching idempotency key.' It does not explain preview_hash, approved_input_hash, resource_version_precondition, request_id, or how the two key fields relate, so the agent cannot confidently populate the nested binding object from the description alone.

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

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

The description states a specific action ('Bind an approved built-in-agent enable preview') and the resource affected, and the title clarifies that this turns on the agent. It is distinguishable from configure_bind by the 'enable' framing, though the term 'bind' is somewhat domain-specific and not fully unpacked.

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 'approved built-in-agent enable preview' implies this is the follow-up to an enable_preview call and requires prior approval metadata. However, it never explicitly names the preview sibling or says when not to use this tool versus configure_bind or other alternatives, so the usage guidance is only implied.

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

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

Beyond the annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description explicitly says 'Side-effect free' and details what the response will contain: the approval-required envelope, what starts happening, what is never sent without you, and binding fields. This gives substantial behavioral context that annotations do not provide.

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

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

The description is a single lean sentence that front-loads the action ('Preview enabling...') and packs in key behavioral and return-value information. There is no redundant or filler content.

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

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

The description excels at explaining purpose and output, but with zero parameter documentation and no mention of idempotency or request_id despite the idempotentHint annotation, it leaves notable gaps. An agent could call the tool but would be unsure how to properly supply parameters, so it is only minimally adequate.

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 the description provides no explanation of the parameters (built_in_agent_id, request_id, idempotency_key). The agent is left without any semantic guidance on which IDs to use or how idempotency works, making this a major gap.

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

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

The description states 'Preview enabling a built-in agent' – a specific verb and resource – and clarifies 'nothing changed yet', making it distinct from the sibling enable_bind tool. The 'Side-effect free' note reinforces that this is a preview, not an actual mutation.

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 clearly indicates this is a preview action and is safe to invoke without side effects, implying it should be used before the actual enable operation. However, it does not explicitly name the alternative bind tool or give an explicit when-not-to-use condition, so it falls short of full explicitness.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by specifying exactly what data the list contains (status, defaults/disabled state, latest work summary), going beyond the minimal 'list' expectation.

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, front-loaded sentence that wastes no words. It states the core action immediately and lists the output details efficiently.

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 operation with no required parameters and no output schema, the description provides sufficient detail about the response content. It lacks mention of pagination or sorting, but these are unlikely to be needed for a catalog listing, making it reasonably 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 coverage is 0% (no descriptions in the schema) and the description does not mention the optional request_id parameter at all. Since the parameter is optional, the agent could omit it, but the description fails to explain its purpose or whether it's needed for tracing or filtering, leaving the agent without guidance.

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

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

The description uses a specific verb ('List') and resource ('built-in-agent catalog') and names three concrete output elements (current status, defaults/disabled state, latest work summary). This clearly distinguishes it from read (single agent) and mutation tools like configure/enable.

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

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

The description implies its use for getting an overview of all built-in agents, but it doesn't explicitly contrast with alternatives like yardstick_built_in_agents_read for a single agent. No when-to-use or when-not-to-use guidance is provided.

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 cover read-only, idempotent, and non-destructive safety. The description adds meaningful behavioral context by stating what the returned data will include, especially 'what it never does without you,' which conveys an important boundary of the agent's autonomous behavior. This goes beyond a bare read operation.

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, well-structured sentence that front-loads the primary action and identifier, then lists the returned content. No wasted words or redundant restatement of the title.

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 compensates by enumerating the expected return content (purpose, safety boundaries, status, work summary). It does not explain the optional request_id parameter, but that is likely a correlation identifier and not central to calling the tool. Overall, an agent has enough 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?

Schema description coverage is 0%, so the description carries the burden. It explains built_in_agent_id well by giving a format ('catalog id') and examples, but it does not mention request_id at all. This leaves one of the two parameters semantically undocumented.

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 verb ('Read'), a specific resource ('built-in agent'), and the key lookup mechanism ('by catalog id'), with concrete examples. It clearly distinguishes this single-item read tool from the sibling list tool by emphasizing 'one' and 'by catalog 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 gives clear context: use this when you need details about a single built-in agent identified by catalog id. It does not explicitly name alternatives or exclusion conditions, but 'one' versus the implied list tool is enough for an agent to infer when to use it.

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 substantial behavioral detail beyond the read-only, idempotent, and non-destructive annotations: the report is flat, excludes candidate/draft/recipient/kit/provider data, and delivery_unknown is never delivered and never retried. It also discloses that results are mode-scoped, which is not present in 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 dense but efficient: each sentence adds information about output shape, per-mode contents, exclusions, delivery_unknown semantics, filtering, and mode scope. There is no redundancy with the title or annotations.

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 with two optional parameters, the description covers what is returned and how to filter by built-in-agent id. The main gaps are the undocumented request_id parameter and the absence of any output field or pagination detail, but the essential invocation context is present.

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

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

The description explicitly maps built_in_agent_id to filtering, but it never explains request_id, its purpose, or whether it is required. Since the schema provides no parameter descriptions and the description covers only one of two parameters, the agent is left with incomplete guidance for invoking the tool.

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 the organization's built-in-agent run history' and clarifies the result is a flat work report. It also identifies the two built-in-agent modes covered, which distinguishes this tool from sibling list tools like yardstick_built_in_agents_list and yardstick_automation_runs_list.

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

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

The description gives useful context for when this tool is relevant, such as nightly screening reports and interview-kit preparation. However, it never names alternative tools or states when not to use this tool, so an agent must infer routing from sibling tool names rather than being told.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the read action—no mention of authentication, rate limits, or what the returned brief contains. With no additional disclosure, this dimension scores low.

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, front-loaded sentence with no filler. While it is essentially a restatement of the title, it is concise and easy to parse, earning a slightly above-average score for structure.

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

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

For a read tool with no output schema, the description should provide enough context for an agent to know what a decision brief is and how it differs from an application read. It does neither, nor does it clarify the role of request_id. The definition is insufficient for confident, correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It only implies that application_id is the key via 'for an application,' but it leaves request_id completely unexplained. Two parameters exist, and the description provides no meaningful detail about either.

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 ('read') and resource ('decision brief') tied to an application, making the core purpose clear. However, it does not explicitly differentiate itself from siblings like yardstick_applications_read or yardstick_decision_brief_regenerate, so it misses the full 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?

There is no guidance on when to use this tool versus alternatives. The description does not mention any context, prerequisites, or exclusions, leaving the agent to infer usage solely from the name.

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 destructiveHint=true and readOnlyHint=false, and the description's 'Regenerate' aligns with mutation. The phrase 'with idempotency metadata' adds a small amount of behavioral context beyond the annotations, but the description does not disclose what happens to the existing decision brief, whether the regeneration is reversible, or what side effects may occur.

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

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

The description is a single concise sentence with no filler, and the core action is front-loaded. It could earn a higher score if it used the saved space to add more practical guidance, but as written it is appropriately brief.

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 mutation tool with no output schema and no parameter-level documentation, the description is too thin. It does not explain the regeneration behavior, overwrite semantics, retry/idempotency usage, or expected outcome, leaving the agent with insufficient context to invoke 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 description coverage is 0%, so the description must compensate, but it only broadly indicates that the tool applies to 'an application' and mentions 'idempotency metadata'. It does not explain the distinct roles of request_id versus idempotency_key, nor why only application_id is required.

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 ('Regenerate') and resource ('a decision brief for an application'), which makes the core action clear. It also distinguishes implicitly from the sibling yardstick_decision_brief_read by using 'regenerate' rather than 'read', though it does not explicitly contrast the two.

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 guidance about when to use this tool versus alternatives such as yardstick_decision_brief_read. It does not state conditions, prerequisites, or exclusions, leaving the agent to infer the appropriate context from the name alone.

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 are all false, so the description carries full responsibility for behavioral disclosure. It only says 'create,' implying mutation, but fails to mention any side effects, confirmation requirements (as hinted by the title), idempotency behavior (despite the idempotency_key parameter), or permissions. The description is minimal and does not add meaningful behavioral context beyond the fact of creation.

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

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

The description is a single concise sentence with no fluff. It front-loads the purpose and is easy to parse. However, it is so sparse that it borders on under-specification, but given its brevity and clarity of action, it earns a 4 for conciseness and structure.

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

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

Given 5 parameters, no output schema, and no annotations, the description is woefully incomplete. It does not explain any parameter semantics, does not mention confirmation steps, idempotency, or any prerequisites. An agent would have no idea how to properly invoke this tool beyond knowing the resource. This is a critical gap for a create operation.

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%, meaning the schema itself provides no parameter explanations. The description does not compensate at all—it says nothing about what each parameter means, which ones are required (only name is required but not stated), or how to use idempotency_key or request_id. This is a severe gap for a tool with 5 parameters.

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

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

The description states a clear verb and resource: 'Create a Department through the public Yardstick API.' It is unambiguous about what the tool does and distinguishes it from sibling tools like yardstick_departments_update by naming the create action. However, it doesn't clarify the 'confirm in Yardstick' aspect from the title, so it loses a point for not differentiating the specific flow.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, confirmation steps, or scenarios where create should be preferred over update or list. The description is purely declarative with no contextual 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?

With readOnlyHint=false, the description correctly implies a mutation, but it only discloses one behavioral aspect (not returning token material). It does not mention side effects like sending an email or requiring confirmation (which the title hints at), nor does it provide context about idempotency or error handling. Given the sparse annotations, the description carries the burden and fails to adequately disclose behavior.

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

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

The description is a single, concise sentence with no filler words. It front-loads the action and includes a relevant behavioral note. However, it may be slightly too terse given the complexity of the tool, but as far as conciseness goes, it is efficient.

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

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

For a tool with 8 parameters, 3 required, no schema descriptions, and no output schema, this description is severely incomplete. It does not explain required inputs, the role enum, expiration behavior, idempotency, or what happens after creation. An agent cannot confidently invoke this tool correctly based on the provided information.

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

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

The input schema has 8 parameters, all with zero description coverage, and the description mentions none of them. It does not clarify the meaning of department_id, email, role, idempotency_key, expires_in_hours, etc. The description provides no compensation for the missing schema descriptions, leaving the agent to guess parameter semantics.

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

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

The description clearly states the action ('Create'), the resource ('invitation'), and the scope ('Department-scoped'). It also adds a specific detail about behavior ('without returning token material'), which makes the purpose unambiguous and distinguishes it from other invitation-related tools like listing.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or other tools (e.g., the sibling list tool). The intended usage is only implied by the name and the word 'Create'.

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 communicate that this is a safe, read-only, idempotent operation, so the description does not need to restate those traits. It adds a little extra context by saying the views are 'redacted,' but it does not explain what is redacted, how pagination behaves, or what the response shape 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?

The description is a single, front-loaded sentence with no filler or repetition. It is concise, though it may be slightly too terse to be fully informative.

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

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

With four parameters, no output schema, and 0% schema description coverage, the description is far too minimal to be complete. It communicates only the basic operation, leaving pagination semantics, the required department parameter, and the meaning of 'redacted' views 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?

Schema description coverage is 0%, and the description adds no parameter-level meaning. Required department_id, limit, starting_after, and request_id are left entirely undocumented, so the description fails to compensate for the schema's lack of explanations.

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 ('List') and a clear resource ('Department invitation views'), and the word 'redacted' adds useful scope about the output. It does not explicitly differentiate from sibling tools, but the naming convention and the absence of other invitation list tools make the purpose reasonably unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent must infer from the name alone that this is the right call for listing department invitations, which is not explicit in the description.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scoping detail ('visible to the current principal'), which is useful behavioral context beyond the annotations. However, it doesn't disclose pagination behavior, ordering, or whether the result includes nested members, which would be relevant for a list operation.

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 no wasted words. It front-loads the verb and resource, and the scoping qualifier is concise. 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 list operation with read-only annotations, the description is mostly adequate. However, with no output schema and no parameter descriptions, an agent might not know what the response looks like or how to use limit/starting_after for pagination. The description doesn't mention pagination or response format, which are common gaps for list tools. Given the simplicity of the tool, this is a minor gap, but it prevents a higher score.

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 carries no parameter information. The schema itself defines three parameters (limit, request_id, starting_after) with basic types and constraints but no descriptions. The tool description doesn't explain what these parameters mean or how they relate to the listing behavior. Since the schema provides minimal semantics and the description adds nothing about parameters, a 3 is appropriate – the parameters are simple and self-explanatory to some degree, but the description doesn't compensate for the 0% 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 'List Departments visible to the current principal' clearly states the verb (list) and resource (departments), and adds a scoping qualifier ('visible to the current principal') that distinguishes it from other department-related tools. It doesn't explicitly differentiate from sibling tools like yardstick_departments_read, but the verb+resource combination is clear enough.

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

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

The description implies usage context: it lists departments visible to the current principal, which suggests it's the appropriate tool for enumerating departments the caller can access. However, it doesn't explicitly state when to use this over alternatives like yardstick_departments_read or yardstick_departments_create, nor does it mention any exclusions or prerequisites.

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 only notes that the person must already exist. It does not explain the 'confirm in Yardstick' behavior suggested by the title, nor what happens on duplicate membership, what side effects occur, or what the response looks like. Annotations indicate idempotent and non-destructive, but the description adds little behavioral context beyond that.

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

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

The description is a single, economical sentence with no filler and is appropriately front-loaded. It is concise, but it omits important context carried by the title, so it is not as complete as it could be while still being short.

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 four-parameter tool with no output schema and no parameter descriptions, this description is too thin. It clarifies the two required identity parameters at a basic level but leaves the optional request_id and idempotency_key unexplained, and the title's confirmation workflow is never addressed. An agent has enough to attempt a basic call but not to use the tool fully and 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 0%, so the description must compensate. It weakly maps 'person' to person_id and 'Department' to department_id, but says nothing about request_id or idempotency_key. An agent cannot understand the meaning or purpose of two of the four parameters from the description alone.

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

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

The description clearly states the action and target: 'Add an existing person to a Department.' This distinguishes it from related member operations like remove and set_lead, though it does not explicitly name a sibling for comparison. The title's parenthetical 'confirm in Yardstick' introduces an ambiguous workflow element that the description does not clarify.

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?

No guidance is given on when to use this tool versus alternatives such as departments_members_remove, departments_members_list, or talent_pool_members_add. There is no mention of prerequisites, such as verifying the person exists or whether the department must already be set up. The intended use is only implied by the name and one-line description.

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, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. It adds only the authorization qualifier and does not disclose pagination behavior, response contents, or ordering. Minimal added value beyond 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 one short sentence with no filler, and the action is front-loaded. It is concise, though it is sparse enough that it adds little beyond the title. Conciseness itself is still good.

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?

As a list tool with no output schema and 0% parameter coverage, the description should explain pagination, authorization requirements, and what is returned. It only gives a one-line purpose, leaving the agent to guess how to use limit and starting_after and what the response shape is. This is incomplete for reliable invocation.

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

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

The schema has 4 parameters (department_id, limit, starting_after, request_id) with 0% schema description coverage, and the description explains none of them. It doesn't say what limit or starting_after control or what request_id is for. The description completely fails to compensate for the schema's lack of 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 ('List') and resource ('Department members'), and the qualifier 'for an authorized Department' narrows scope. It reads distinctly from siblings like yardstick_departments_members_add or yardstick_departments_list, though it doesn't explicitly name an alternative. This is clear but not actively differentiating.

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?

No explicit when-to-use or when-not-to-use guidance is given. The phrase 'authorized Department' implies a prerequisite, but there is no discussion of alternatives or conditions for choosing this list tool over other department member tools. Usage is only implicit.

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, idempotentHint=true, and readOnlyHint=false, and the description does not contradict them. The description adds the nuance that removal can optionally install a replacement lead, but it does not disclose consequences such as whether removing the current lead requires a replacement or whether the '(confirm in Yardstick)' title implies a confirmation step.

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

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

The description is one tight sentence with no filler and front-loads the primary action. It is concise, though slightly under-specified for a five-parameter destructive operation.

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 call with five parameters, no output schema, and 0% parameter documentation, a single sentence leaves important gaps: no mention of confirmation semantics, what happens to leads, when idempotency_key or request_id are needed, or what a successful removal returns. The annotations cover idempotency and destructiveness, but the description alone is not enough for confident invocation.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It clarifies replacement_lead_person_id as an optional replacement lead, but it does not explain the role of request_id or idempotency_key and only restates the obvious meaning of department_id and person_id, so it fails to compensate for the missing schema descriptions.

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

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

The description uses a specific verb ('Remove') and resource ('Department member'), and adds the optional replacement-lead behavior, making the core action clear. It does not explicitly contrast with sibling tools like yardstick_departments_members_add or yardstick_departments_members_set_lead, but the name and action together are 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?

No guidance is provided about when to use this tool versus alternatives such as yardstick_departments_members_set_lead or yardstick_talent_pool_members_remove. The description states what the tool does but gives no conditions, prerequisites, or exclusions, so an agent must infer applicability from the name alone.

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 signal destructive and idempotent behavior. The description adds only 'one member,' which is essentially the core action and not meaningful behavioral context. It doesn't explain what happens to a previous lead, whether confirmation is required despite the title's 'confirm in Yardstick,' or what side effects occur.

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, short, front-loaded sentence with no filler. It is efficient in form, though the brevity comes at the cost of missing important contextual details.

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, no parameter descriptions, and multiple optional parameters, this description is incomplete. It fails to mention the fixed role value, idempotency handling, or confirmation behavior, so an agent cannot confidently invoke the tool correctly in all cases.

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, but it explains none of the five parameters. It doesn't clarify department_id, person_id, role's fixed 'lead' value, request_id, or idempotency_key, leaving the agent to infer their meaning from names alone.

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

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

States a clear action ('Set one Department member as lead') with a specific resource and role. It is unambiguous enough to distinguish from sibling member tools like add/remove, but it does not explicitly name those siblings or call out the 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?

No guidance is given about when to use this tool versus departments_members_add, departments_members_remove, or departments_members_list. It also fails to mention whether a department lead already exists, whether confirmation is required, or any prerequisites.

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 convey readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds the useful identifier nuance of 'public id' and singular result, but does not mention response shape, not-found behavior, or any other runtime details.

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, tight sentence with no filler. The core operation and key detail are front-loaded and every word contributes.

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

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

For a simple read tool with rich safety annotations, the description captures the essential invocation details. However, with no output schema and no mention of return or error behavior, an agent has some ambiguity about what to expect from the call.

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?

With 0% schema description coverage, the description carries the parameter burden. It usefully clarifies that department_id is the public identifier lookup key, but the optional request_id is left entirely unexplained, creating a partial coverage gap.

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

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

The description names the exact operation ('Read'), the resource ('Department'), and the lookup key ('by public id'). It clearly distinguishes this from departments_list and departments_update without needing to inspect the schema.

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?

'Read one Department by public id' gives a clear context: use this when you need a single department and have its public identifier. It does not explicitly name alternatives or exclusions, but the singular 'one' and the sibling department tools make the appropriate usage evident.

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 destructive and idempotent behavior, and the description adds no extra behavioral context. It does not explain side effects, reversibility, or the 'confirm' workflow hinted at in the title, leaving the agent without critical operational insight.

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 with the core action, but 'schema-bound public API fields' is low-value filler that could be removed. It is not overly verbose, but it lacks meaningful content that would justify 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 destructive update tool with six parameters and no output schema, the description is far too sparse. It does not clarify the confirmation workflow hinted at in the title, nor any preconditions, side effects, or expected results, leaving significant gaps for an agent.

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

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

Schema description coverage is 0%, and the description does not explain any of the six parameters. The phrase 'schema-bound public API fields' is unhelpful filler; the agent must rely solely on parameter names in the schema, which is insufficient for correct invocation.

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 ('Update one Department'), which distinguishes it from create/list/read siblings. However, the phrase 'schema-bound public API fields' is vague and adds no specific detail about what fields are updatable, though the schema lists them.

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?

No guidance is provided on when to use this tool versus alternatives like create or other department tools. The verb 'Update' implies modifying an existing department, but no prerequisites, exclusions, or alternative conditions are mentioned.

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 matches annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and adds no contradictory claims. However, it adds no behavioral context beyond what the annotations already establish, so it provides only baseline adequacy.

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 short sentence with no filler and the main verb is front-loaded. It is concise, though it is concise to the point of omitting useful context.

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

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

There is no output schema, no explanation of return values, no parameter semantics, and no distinction from closely related email-settings read tools. An agent cannot confidently infer what will be returned or how request_id affects the 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 description coverage is 0%, and the only parameter, request_id, is optional and undocumented. The description never mentions request_id or explains when or why an agent would supply it, so the agent gets no assistance beyond the bare property name.

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 ('Read') and identifies the resource as 'candidate email automation settings.' It is clearly a read operation and is distinguishable from the sibling update tool by the read/write split, though it does not explicitly name or contrast any 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?

No guidance is given for when to use this tool versus the update tool or other email settings reads like yardstick_email_sender_settings_read. The read-only nature is implied by the verb but no exclusions or alternative conditions are provided.

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 idempotentHint=true, but the description adds no behavioral context—it does not explain that updates may overwrite existing settings, nor does it mention the idempotency_key's role. The description carries no extra 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 a single generic sentence that is terse but not concise in a helpful way—it omits essential information. It is under-specified rather than efficiently 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 mutation tool with destructiveHint=true and no output schema, the description is severely incomplete. It lacks any explanation of the settings being updated, how to provide them, or what the request_id and idempotency_key are for. An agent cannot correctly invoke this tool based on the description alone.

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 the description does not mention either parameter (request_id, idempotency_key). It fails to explain what these parameters do or how to specify the actual settings to update, leaving the agent without critical usage information.

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 clear verb (update) and resource (candidate email automation settings), which is specific and distinguishes it from the read counterpart. It does not explicitly name sibling alternatives, but the verb and resource make 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?

There is no guidance on when to use this tool versus alternatives. While the read sibling is obvious, the description provides no context about when updates are needed, prerequisites, or 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 destructiveHint=true and idempotentHint=true, but the description adds minimal context: it says 'without provider mutation', which is somewhat counterintuitive given destructiveHint. There is no mention of what happens to the draft, whether it is recoverable, or what the response is. The description does not contradict annotations but does little to explain the behavior 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 a single sentence, concise and front-loaded with the primary action and resource. However, it is too brief given the lack of parameter documentation, but as far as structure, it is adequate.

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

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

The tool has three parameters, no output schema, no enums, and annotations carry only basic hints. The description does not explain the state of the draft, the effect of discarding, or the idempotency implications. Given the complexity of a destructive action with idempotency keys, more context is expected.

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 the description does not explain any of the three parameters. The id, request_id, and idempotency_key are defined only by their names and types, which is insufficient. The description should clarify that id identifies the draft and that request_id and idempotency_key are optional for idempotency, but it does not.

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 (discard), a specific resource (candidate email draft), and the state (pending). It distinguishes from siblings like send, update, and list by focusing on discarding. It does not explicitly mention the alternative tools for discarding (e.g., a delete or discard action) but the verb is clear.

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

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

The description implies usage when discarding a pending draft, but provides no when-to-use guidance such as prerequisites (e.g., draft must be pending, not sent) or alternatives (e.g., use update to modify instead). There is no mention of when not to use.

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 cover the read-only, non-destructive, idempotent behavior, so the bar is lower. The description adds only the vague 'history and provenance' notion, but does not disclose what the returned history contains, how far back it goes, or how versions are represented.

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 compact, front-loaded sentence with no filler. It is concise, though the brevity comes at the cost of parameter and usage detail.

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

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

For a tool with two parameters and no output schema, the description is too thin. It omits parameter semantics, return format, and any guidance distinguishing it from related email draft tools, so an agent may not call it correctly without external 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 description coverage is 0%, and the description provides no parameter guidance. It does not clarify whether 'id' is a draft identifier or candidate identifier, nor what the optional 'request_id' means or how it affects results.

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 ('Read') and resource ('candidate email draft history and provenance'), making the tool's general purpose clear. It does not explicitly differentiate itself from sibling tools like yardstick_email_drafts_read or yardstick_email_drafts_list, but the 'history' scope is enough to distinguish it at a basic level.

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 word 'history' implies when this tool is appropriate: when an agent needs historical versions or provenance rather than the current draft. However, the description does not explicitly name alternatives or state when not to use this tool, leaving the routing decision mostly 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds no behavioral context beyond that, such as whether filters are combined with AND/OR, default ordering, or pagination behavior. Since annotations carry the safety burden and the description does not contradict them, a 3 is appropriate – it adds minimal but not insufficient value.

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, efficient sentence that front-loads the action and resource, then mentions the optional filters. There is zero waste; every word contributes to the meaning. It is appropriately concise for a simple listing operation.

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 absence of an output schema and 0% schema coverage, the description leaves critical details unstated: pagination via starting_after, limit behavior, what 'candidate' means in this domain, and the return format. The tool is not fully self-contained; an agent would need additional context or documentation to use it correctly beyond a basic list call.

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?

With 0% schema description coverage, the description must compensate for all five parameters. It only mentions 'status' and 'email-type' filters, leaving 'limit', 'starting_after', and 'request_id' undocumented. The description does not explain pagination, default limits, or the role of request_id, so an agent cannot correctly invoke the tool with full parameter awareness.

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 'List' and the resource 'candidate email drafts'. It distinguishes from sibling tools by the verb 'list' versus 'send', 'update', 'preview', etc., though it does not explicitly name alternatives. The purpose is unambiguous and specific enough for an agent to understand the core function.

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 no guidance on when to use this tool versus other email draft tools (e.g., read, preview, send). It does not mention any context like 'use this to see all drafts' or 'when you need a collection of drafts'. There is no mention of alternatives or when not to use it, leaving the agent to infer usage from the verb alone.

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, idempotentHint, and destructive false, so the safety profile is covered. The description adds that the operation returns 'rendered preview content' rather than raw draft metadata, but it doesn't explain response format or error behavior. It does not contradict 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?

A single eight-word sentence with no filler. The main action and object are front-loaded rank. It sacrifices detail for brevity but remains an efficient statement.

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, annotations already handle safety, but the description omits parameter purposes and any return/rendering details. Without an output schema, more guidance on what the preview content consists of would improve completeness.

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 the description does not explain the meaning of `id` or `request_id`. While `id` is somewhat self-evident, `request_id` is ambiguous and the description provides no clarification for either parameter.

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

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

The description uses the specific verb 'Read' with the object 'rendered preview content,' identifying the exact resource as 'candidate email draft.' This clearly distinguishes it from siblings like yardstick_email_drafts_read and other preview tools by emphasizing rendered output and candidate-specific 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?

No explicit when-to-use or when-not-to-use guidance is given. The purpose implies it is for previewing a draft before sending, but no alternatives are named or conditions 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 establish read-only, idempotent, non-destructive behavior, and the description adds the 'redacted' detail, signaling that returned content is masked. It does not explain what is redacted or how request_id affects the response, but the annotation coverage lowers the burden.

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 single sentence is efficient and front-loads the key operation and the redaction trait. It is appropriately short, though it adds only the word 'redacted' beyond the title.

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 operation with strong safety annotations, this is minimally adequate: an agent can infer that id is the draft ID and that the call is safe. But without parameter semantics, sibling differentiation, or output formatting, it leaves meaningful gaps for an agent deciding between read, preview, and history.

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's parameters are bare (id, request_id) with 0% description coverage, and the description does not clarify what these identify or how they relate. Little semantic value is added beyond the parameter names.

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 verb 'Read' and resource 'redacted candidate email draft' specify the operation clearly. However, it does not explicitly distinguish itself from sibling tools like email_drafts_preview or email_drafts_history, so some inference is required.

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 guidance on when to use this tool rather than email_drafts_list, email_drafts_preview, or email_drafts_history. No exclusions, prerequisites, or alternative routing are provided.

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