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, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is largely covered structurally. The description adds scope-limiting context ('does not schedule interviews or send email') and the review precondition, but says nothing about reversibility (an undo sibling exists) or required permissions.

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

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

Two short, front-loaded sentences with no filler; the core action comes first and the scope limitation second. It is efficient, though arguably too terse given the surrounding gaps.

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 in a dense sibling set (undo_candidate_admission, decide, transition_direct/bind/preview), the description covers the core action and one negative boundary but omits preconditions of 'reviewed', the reversal path, and any parameter meaning. Adequate but with clear 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?

Three parameters with 0% schema description coverage: application_id is only obliquely implied by 'one reviewed application', and request_id and idempotency_key are completely unexplained. Given that idempotency_key semantics (safe retry) are operationally important for a mutation, the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Move one reviewed application to Candidates'), which clearly distinguishes it as a stage-transition mutation rather than a read or create. However, it never names its closest siblings (yardstick_applications_undo_candidate_admission, yardstick_applications_decide, the transition_* family), so an agent must infer the boundary from the name alone.

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 'one reviewed application' implies a precondition (the application must already be reviewed) and the trailing sentence rules out adjacent behaviors (interview scheduling, email), which narrows usage somewhat. But there is no explicit when-to-use statement or routing to alternatives such as undo_candidate_admission for reversal.

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 declare destructive/idempotent/not-readOnly, and the description adds real value beyond them: the authorization rule (non-HM callers get 'application not found'), the reason-code constraint (system or org codes only), and the concrete consequence that 'Reject disqualifies the candidate'. It still says nothing about idempotency or the scheduling side effect of approve_and_schedule.

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

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

Three dense sentences, zero filler, and the most decision-critical constraint (permission gate) is front-loaded after the one-line purpose 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 6-parameter mutation tool with no output schema and 0% schema coverage, the description covers authorization, reason codes, and the reject consequence but omits idempotency/request-id semantics and parameter documentation, leaving clear gaps an agent must guess at.

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% across 6 parameters, so the description carries the full burden but only partially compensates: it constrains reason_code_ids and hints at the 'reject' decision value, while note, request_id, idempotency_key, and the other four decision enum values are never 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?

States a specific verb ('Decide') and resource ('application') and adds the scoping qualifier 'without a review task', which separates it from decision paths that involve review tasks or the email-decision apply/preview siblings. It is clear, though it does not name the specific sibling alternative by name.

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

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

The description gives a permission gate (only the hiring manager) and an implicit scenario ('without a review task'), but it never explicitly names when to prefer this over yardstick_applications_transition_direct or yardstick_applications_email_decision_apply. Usage is implied rather than stated.

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

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

Annotations already establish that this is a non-read-only, idempotent, non-destructive operation. The description adds meaningful behavior beyond that: who is authorized to decide, how to target the latest waiting step when interview_id is omitted, and how a note can be routed to the recruiter via send_to_recruiter.

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

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

Three front-loaded sentences with no filler. The core action and scope come first, followed by permission and targeting details, then the optional note behavior. Every sentence contributes relevant information.

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

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

For a mutation tool with no output schema, the description covers the essential purpose, authorization, targeting behavior, and a side-effect option. Rich annotations handle idempotency and safety signals, though the unexplained request_id and idempotency_key parameters keep it from being fully 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 must carry parameter meaning. It explains decision, interview_id, note, and send_to_recruiter, but leaves application_id, request_id, and idempotency_key entirely unexplained. It partially compensates for the low schema coverage, but not fully.

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 and resource: advance or hold a candidate on a hiring-manager step, or change that decision. It clearly scopes the tool to steps that wait on the hiring manager. It does not, however, distinguish itself by name from similar siblings such as yardstick_applications_decide or yardstick_applications_hiring_step_decision.

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 usable context: the hiring manager or a recruiter on the job may decide, and interview_id may be omitted to target the latest such step. It does not explicitly say when to prefer this tool over sibling decision tools or when not to use it, so the routing guidance remains 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 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral value by enumerating the possible decision states returned (advanced, held, waiting, none), which is otherwise absent since there is no output schema.

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

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

A single tight sentence that front-loads the verb and resource and ends with the useful return-value enumeration. No filler.

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

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

For a simple read tool with annotations carrying the safety profile and no output schema, the description covers purpose and return states adequately. However, the two parameters are undocumented and the phrase 'step that waits on one' is slightly convoluted, leaving an agent to infer the scoping 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% and the description never mentions application_id or request_id. The application_id name is self-evident, but request_id (likely an idempotency/correlation key) is entirely unexplained in either the description or the schema.

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

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

States a specific verb ('Read') and resource (the hiring manager's decision on the candidate's latest pending step), which is enough to distinguish it from the write sibling yardstick_applications_decide_hiring_step. It does not explicitly name that sibling, so an agent must infer the read/write split, but the purpose itself is 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 explicit when-to-use guidance, no statement of prerequisites, and no routing to alternatives such as yardstick_applications_read or yardstick_applications_decide_hiring_step. The read-only intent is only implied by the verb 'Read'.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful scope qualifier 'visible to the current principal', which clarifies permission-limited results, but says nothing about pagination behavior or result shape — analogous to the calibration case that earned a 3.

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

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

Two tight sentences: purpose first, filter guidance second, with no filler. The CLI-style '--param' notation is mildly informal but compact and front-loads the essential information well.

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 5-parameter list tool with no output schema and 0% schema description coverage, the description should at least mention pagination (limit/starting_after) and the request_id purpose. It adequately explains scoping and two filters but leaves the remaining parameters and result behavior to guesswork.

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, yet it only explains 2 of 5 parameters: job_id (with a use case) and hiring_manager_decision (repeating the enum values). The limit, request_id, and starting_after parameters — including pagination — are left entirely undocumented in both places.

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

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

The description states a specific verb (List) and resource (application person + Job attachments) with an explicit visibility scope, so an agent can distinguish it from yardstick_applications_read or the many mutation siblings. The phrasing 'application person + Job attachments' is slightly awkward but conveys that it returns applications linking people to jobs.

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

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

It gives concrete when-to-use guidance for two filters: --job-id 'to find candidates for a role' and --hiring-manager-decision 'for where the hiring manager's decision stands'. However, it never contrasts with alternatives such as yardstick_applications_read (single record) or people_list, so routing guidance is incomplete.

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 declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description adds non-obvious behavior beyond them — the no-time-limit rule, that it is refused once candidate activity begins, that history is preserved, and that the episode is excluded from admission reporting. These operational and reporting side effects are exactly the added value annotations cannot convey.

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

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

Three short sentences, each carrying distinct information (action, timing/refusal rule, side effects), with the core purpose front-loaded and no filler.

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

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

For a destructive, idempotent mutation with no output schema, the description covers preconditions, reversibility semantics, and reporting side effects well. The remaining gap is parameter-level detail, since none of the four fields are described in the schema.

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

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

Schema description coverage is 0% with four parameters, so the description must carry the full burden. It only explains expected_admission_id ('its current admission ID', implying the concurrency check) and says nothing about application_id, request_id, or idempotency_key, leaving three of four parameters undocumented anywhere.

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

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

States a specific verb and resource ('Correct one accidental candidate admission') and names the identifying key (the current admission ID). An agent can distinguish this corrective undo from the sibling yardstick_applications_admit_candidate without opening either 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?

'No time limit; refused once candidate activity starts' gives a concrete precondition that determines when the call will succeed or fail. It is clear context, but it does not explicitly contrast the tool with alternatives such as admit_candidate or the transition/decide 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 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 already declare destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: the mandatory preview-then-apply gate, explicit user confirmation before applying, reporting of affected and skipped rules, the pick-a-step skip behavior when switching on, and the blast-radius warning that shared pipeline rules change for every job on that pipeline. That is exactly the behavioral disclosure a destructive bulk operation needs.

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

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

Every sentence is an instruction with no filler, and the workflow order is front-loaded. It is dense — five imperative sentences in a single undifferentiated block — but nothing could be cut without losing operational 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?

For a destructive 6-parameter bulk tool with a nested filter object, no parameter descriptions and no output schema, the description covers the critical safety workflow and the preview return contents (affected/skipped rules). It falls short on filter semantics and the request_id/idempotency_key parameters that an agent would need for correct retry behavior.

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 mode (preview vs apply), rule_ids (exact ids from preview) and implies action ('switch on, off or delete'), but says nothing about the filter's fields, request_id, idempotency_key, or the 500-item cap on rule_ids.

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 specific verb set (switch on, off, delete) and the resource (automation rules in bulk), so an agent can tell it apart from single-rule siblings like yardstick_automation_rules_update or yardstick_automation_rules_delete. It never explicitly names those siblings, so the differentiation is inferential rather than stated.

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?

Strong procedural guidance: 'First use mode=preview with rule_ids or filter', 'Then use mode=apply with only the exact rule_ids returned by preview; never reapply the filter' — a clear when-to-do-what sequence with an explicit prohibition. It does not compare against alternative tools (e.g. single-rule update/delete) for cases where bulk is unnecessary.

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 that this is a mutation (readOnlyHint=false) that is not idempotent and not destructive. The description adds substantial non-obvious behavior: matching is by step name/kind and position for steps, by name or mapped status for stages; unmatched copies start disabled and need manual step/stage selection; copies become independent user rules. That is real context beyond the structured hints, though return/idempotency behavior is still unstated.

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

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

Three dense sentences, front-loaded with the core action and destination, then matching rules and the unmatched-copy consequence. Every sentence carries information, though the 'Pick a step' / 'Pick a stage' UI phrasing is somewhat opaque without that 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?

No output schema exists, so return values need not be described, and the mutation's safety profile is covered by annotations. However, for a copy tool exposing request_id and idempotency_key while declaring idempotentHint=false, the description leaves deduplication/retry semantics and any permission requirements 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% across 5 parameters, so the description must carry the full burden. It meaningfully explains job_ids, pipeline_ids and rule_id, but leaves request_id and idempotency_key completely undefined, and gives no format or constraint detail (e.g. the 50-item cap) for the arrays.

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

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

States a specific verb (Copy) and resource (rule), and even splits purpose into two modes: a hiring-process rule copied to job_ids, or a pipeline rule copied to pipeline_ids. This clearly differentiates it from the automation_rules_create/update/delete siblings, though it never names an alternative 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 two copy modes imply when the tool applies, but there is no explicit when-to-use guidance, no exclusions, and no pointer to alternatives like automation_rules_create or automation_rules_preview. Usage must be inferred from the two described scenarios.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so safety profile is known. The description adds one genuinely useful fact beyond that: authoring executes no action at creation time. It does not cover idempotency_key/request_id behaviour or whether an invalid rule aborts atomically.

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

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

Two tight sentences with no waste, and the core purpose is front-loaded. The closing clause about not executing an action earns its place; nothing is padded.

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

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

Given 17 parameters, deep nesting and no output schema, the description is thinner than the tool's complexity warrants, though the schema's enums and nested descriptions carry much of the load. It omits how job_scope selected vs all_compatible interacts with job_posting_ids, and how this tool relates to the preview/preview_draft siblings before committing a rule.

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% overall, so the description must compensate, and it names the main parameter domains: trigger (stage/step), job_scope, delivery_mode, timing and a typed action. That clarifies the discriminator concept and the trigger family, but leaves condition, position, needs_step_pick, job_posting_ids and the idempotency fields unexplained.

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

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

States a specific verb (Create) and resource (named workflow automation rule) plus the components it accepts: triggers, job scope, delivery mode, timing, typed action. This separates it from read/update/delete siblings, though it never explicitly names preview/bulk/copy as alternatives.

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, and no routing to sibling tools such as yardstick_automation_rules_preview, _update, _bulk or _starters_apply. The only usable inference is that authoring is safe to attempt because it executes nothing.

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, so the safety profile is covered structurally. The description adds genuine value beyond that by explaining the blast radius (rules are inert config; deleting unfired config moves no candidates), which tells the agent why this destructive call is low-risk. It omits permissions requirements and the fact that request_id serves as an idempotency key.

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

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

Two tight sentences, front-loaded with the action and then the risk rationale; nothing redundant. The parenthetical "no approval preview→bind" is notation-dense and slightly harder to parse than plain prose, but it earns its space.

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 with no output schema, the description covers purpose and blast radius, and annotations cover idempotency/destructiveness. It is still thin on parameter semantics (especially request_id) and error/failure behavior, so it is adequate but with visible 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% for two parameters, so the schema names rule_id and request_id without explaining either. The description adds no parameter meaning at all — nothing about rule_id format or that request_id is an idempotency/replay key — leaving the burden unfulfilled despite the low coverage.

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

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

The description opens with a specific verb+resource ("Delete an automation rule") and immediately scopes it as a plain delete rather than the preview→bind pattern used by sibling operations, so an agent can distinguish it from yardstick_automation_rules_preview, _preview_rule, and the bind-style siblings 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?

By stating "Plain delete (no approval preview→bind)" it clarifies the condition under which this direct tool is used instead of a preview/approval flow, which is meaningful routing guidance in this sibling set. It stops short of explicitly naming the alternative tools or stating when deletion is inappropriate, so it is clear context but not a full when/when-not rule.

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 one behavioral nuance — that job/department filters surface inherited pipeline rules and pipeline filters surface hiring-step rules — which shapes what the caller actually receives. It says nothing about pagination, result cap, or ordering, so it is adequate but not rich.

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

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

Two sentences, both front-loaded with the operation then the filter semantics. There is no filler, repetition of the title, or restatement of schema types — 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?

There is no output schema, so the description is the only source of shape information, and it covers what entities are returned and how inheritance expands results. It omits pagination/limits and default ordering, which an agent listing potentially large rule sets would want, but the essentials for a read-only list call are present.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it documents 6 of 7 parameters (job_id, department_id, pipeline_id, trigger, email, is_active) with semantic detail such as job_id being null for pipeline rules. Only request_id is left unexplained, which is a minor gap but prevents a perfect score.

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

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

States a specific verb and resource ('List all job and pipeline rules') and clarifies the scope is both job- and pipeline-level rules. This distinguishes it from yardstick_automation_rules_read (single rule), but it does not explicitly name any sibling or contrast the list/read pair, so it stops short of a 5.

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

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

The description gives real filtering context ('job_id null for pipeline rules', which filters include inherited pipeline rules and hiring-step rules), which is useful for choosing the right query. However, it never states when to use this tool versus automation_rules_read or automation_runs_list, and there are no 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 establish readOnly, idempotent, and non-destructive behavior, but the description adds concrete non-effects: no scheduling link, no task, no email, nothing executed. That directly addresses the main risk an agent would worry about when previewing automations, though auth and rate-limit context are absent.

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

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

Two tight sentences, front-loaded with the operation and followed by the safety guarantee. Every clause earns its place; there is no repetition or filler.

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

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

The description covers purpose, return content (active rules plus resolved action params), and inertness, which is useful without an output schema. But with five parameters at 0% schema description coverage and no explicit usage routing, it is not fully complete for 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 carry parameter meaning. It only vaguely maps to application_id and stage/trigger via 'sample application entering/leaving a stage' and says nothing about request_id, idempotency_key, or the trigger enum values, leaving most parameter semantics 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 states a specific verb and resource: dry-run preview that resolves the active rules and their resolved action params for a sample application entering/leaving a stage. This scope clearly distinguishes it from siblings like automation_rules_list and automation_rules_preview_rule without requiring either 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 phrase 'Dry-run preview' implies this is the safe way to see what automations would fire before a real stage change, which is useful implied usage. However, it names no explicit alternative (e.g., transition_preview, preview_rule, transition_direct) and gives no when-to-use or prerequisite 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 declare readOnlyHint, idempotentHint, destructiveHint: false, and openWorldHint: false. The description reinforces that it saves nothing and executes no action, which is useful, but it adds little about preconditions, error behavior, or what the preview 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?

Three compact sentences, front-loaded with purpose, then invocation detail, then the no-side-effects guarantee. The CLI example earns its place and there is no filler.

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

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

For a tool with a deeply nested rule schema, no output schema, and only 25% schema description coverage, the definition is thin. It omits what the preview returns, how application_id is used beyond the vague 'real application' phrase, request_id semantics, and validation/error behavior.

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

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

Schema description coverage is only 25%, so the description needs to compensate. It explains the main rule parameter as create-style input with a CLI example and explains conditional rule_id, but application_id is only weakly implied by 'for a real application' and request_id is never explained.

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 (Preview) and resource (an unsaved workflow rule) and scopes it to a real application. It clearly distinguishes previewing from saving, but the reference to 'preview-rule' does not explain how this tool differs from that sibling.

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

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

It gives a clear before-saving context and explains when to add rule_id for unsaved edits. However, it does not say when to choose this over yardstick_automation_rules_preview or yardstick_automation_rules_preview_rule; saying it gives the 'same result as preview-rule' muddies selection rather than 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying what the preview returns (recipients, sender, rendered email, scheduling links, missing prerequisites) and reinforcing that it executes no action.

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

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

The description is a compact, front-loaded sentence followed by a short safety clause. It is appropriately sized and wastes little space, though 'Executes no action' partly repeats the title and readOnlyHint annotation.

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 carries the burden of explaining the return and it does list several preview outputs. However, it omits any mention of the optional request_id parameter and does not explain error behavior or prerequisite-check outcomes in detail.

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 loosely maps 'saved workflow rule' to rule_id and 'real application' to application_id, but it provides no semantics for the optional request_id parameter and no format or constraint details for any 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 gives a specific verb (Preview) and resource (a saved workflow rule) and even lists what the preview surfaces, which is clearer than a generic read. However, it does not distinguish itself from the sibling yardstick_automation_rules_preview or yardstick_automation_rules_read, so an agent must infer the difference.

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 validation context by noting it is 'for a real application' and reports 'missing prerequisites', but it never states when to choose this tool over the existing preview or read siblings. There are no exclusions or explicit alternatives 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description needn't restate the safety profile. It adds value by naming the fields returned (trigger, typed action, target stage, is_active), but says nothing about what happens on an unknown id or authorization requirements.

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

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

One tight sentence that front-loads the verb, resource, key parameter, and return shape with zero filler.

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

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

For a simple read tool with full read-only annotations and no output schema, the description is largely adequate, but the missing request_id semantics and error behavior leave gaps in a 0%-coverage 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 should compensate for two undocumented parameters. It identifies rule_id implicitly as the public id, but says nothing about request_id or the string/minLength constraints.

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

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

States a specific verb and resource ('Read one automation rule') and scopes it by public id, distinguishing it from list, preview, create, update, and delete siblings in the automation_rules family. The parenthetical previews the returned shape, reinforcing what the tool fetches.

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 'by public id' implies a lookup of an already-known rule, which differentiates it loosely from yardstick_automation_rules_list and the preview tools, but no explicit when-to-use or when-not-to-use 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond the field list: it does not say whether this is a partial patch (fields omitted are preserved) or a replace, what happens to in-flight runs, or that rule_id is required. No contradiction with annotations, but no added behavioral context either.

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

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

A single front-loaded sentence with no filler, and the mutable facets come early. It is efficient, though its brevity is partly under-specification rather than discipline given the tool's complexity.

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?

An 18-parameter destructive mutation with deeply nested action/condition/timing objects, no output schema and 0% schema coverage needs far more than one sentence. An agent cannot tell what a partial edit preserves, which field combinations are valid, or how omitted fields behave.

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% across 18 parameters, so the description carries the burden and largely fails. It names roughly eight fields but never explains the required rule_id, the 19-value trigger enum, the seven-branch action union, timing anchors, job_scope vs job_posting_ids, or the idempotency_key/request_id distinction.

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

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

States a specific verb ('Edit') plus the resource ('workflow automation rule') and enumerates the mutable facets (trigger, action, condition, job scope, delivery mode, timing, active state). That is enough to separate it from create/delete/copy siblings, though it never names those siblings or the preview/read tools an agent might need first.

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 on when to use this versus yardstick_automation_rules_preview, preview_rule, copy, bulk or create, and no prerequisites (permissions, whether the rule must be inactive, whether a read is required first). The only signal is the verb 'Edit', which is implied usage at best.

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 non-destructive, so the safety profile is covered. The description adds genuinely new context beyond the annotations: that runs are system-written (i.e., not user-creatable) and an enumeration of the returned fields, which matters because there is no output schema.

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

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

Three tight clauses, front-loaded with the resource and its returned fields, then filters, then the read-only caveat. No filler sentences and nothing is buried.

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 3-parameter, no-output-schema read tool, the description covers the returned fields and two of three filters, which is nearly enough to invoke correctly. The gaps are the unexplained request_id and the absence of any pagination or filter-combination guidance.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It documents two of the three filters (application-id, rule-id) but leaves request_id entirely unexplained, and adds no format or combination semantics for the ones it does 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 states a specific verb and resource ("List workflow automation runs") and enumerates the fields surfaced by the list, so an agent knows exactly what it gets back. It does not explicitly differentiate itself from the sibling yardstick_automation_runs_retry, but the read-only framing implicitly separates it from the mutating 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?

It gives partial usage guidance by naming the two filter dimensions (application-id, rule-id), which tells the agent how to scope the call. However it offers no when-to-use/when-not framing and never points to the retry sibling for acting on a failed run, leaving alternatives 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, idempotentHint=false and readOnlyHint=false, so safety is covered structurally. The description adds genuine behavioral detail beyond that: the refusal conditions and which run states are eligible. It does not explain the side effects or cost of a re-run, so it is not fully complete.

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

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

Two tight sentences, front-loaded with the action and then the eligibility constraint. Nothing is padded or redundant.

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, non-idempotent mutation with annotations covering the safety profile and no output schema, the eligibility rules are useful. However, the two undocumented parameters and the lack of any note on re-run side effects leave real 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 says nothing about run_id or request_id. run_id is self-evident from its name, but request_id (plausibly an idempotency/dedupe key) is left entirely undocumented in both schema and description.

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

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

The description names a specific action (re-run a workflow run) and its precondition (after fixing missing setup), which is clear and distinct from the read-only sibling yardstick_automation_runs_list. It stops short of naming alternatives, but the verb+resource is 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?

It states the eligibility condition explicitly: only clean refusals and active rules qualify, and unknown outcomes are refused. That tells the agent when this tool will succeed versus fail, though it names no alternative action for the refused cases.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive operation. The description adds genuinely useful behavior beyond that: unmatched rules are left off and existing rules are preserved. It omits auth/permission needs, whether the operation can partially fail, and the meaning of idempotency_key given idempotentHint=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?

A single compact sentence with the copy action and the key preservation guarantee front-loaded. There is no padding, though brevity here edges toward under-specification rather than efficiency.

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 six-parameter mutation tool with nested objects, no output schema, and zero schema descriptions, the description is too thin. An agent cannot determine from it how matches map rules, what source_digest validates, or what a successful apply returns, so it is not complete enough to call 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% across six parameters, including nested matches and a hex-patterned source_digest. The description only vaguely gestures at 'chosen matches' and never explains request_id, source_digest, idempotency_key, or how the source type enum (starter vs job) is used, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb (Copy) and resource (reviewed rules into a job), which is more informative than the bare tool name. However, it does not distinguish this tool from close siblings like yardstick_automation_rules_copy or yardstick_automation_starters_save_job, leaving the agent to infer which copy path applies.

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 hints at the mechanism ('using chosen matches') but gives no explicit when-to-use, when-not-to-use, or alternative tools. With several overlapping copy/save starter siblings present, the lack of routing guidance is a real gap.

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 the safety profile (not read-only, not open-world, not destructive, not idempotent), so the bar is lower. The description adds real context beyond that: the starter is organization-scoped and is built from 'portable rule definitions'. It still omits behavior on name collisions, whether the starter is reusable elsewhere, and the meaning of the idempotency_key parameter.

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

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

A single front-loaded sentence with no filler; the verb and resource lead. It is efficient but so terse that terseness shades into under-specification rather than disciplined brevity.

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

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

For a write tool with four parameters, 0% schema description coverage, and no output schema, one sentence is not enough. It says nothing about request_id/idempotency_key, conflict handling, or what the created starter's identity/return looks like, so an agent calling it correctly is largely guessing.

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 and only partially meets it: 'named' maps to name and 'portable rule definitions' maps to rules. The request_id and idempotency_key parameters are undocumented in both the schema and the description, leaving half the parameters opaque.

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

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

States a specific verb (Create), resource (organization starter), and input source (portable rule definitions), which clearly separates it from the read/list/delete/rename starter siblings. It does not, however, distinguish itself from automation_rules_create or automation_starters_apply/save_job, so the agent must infer which of the create-family tools it wants.

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 when-to-use guidance, no prerequisites, and no mention of the alternatives (starters_apply, starters_preview, automation_rules_create) that share this name prefix. The agent gets no signal about when creating a starter is the right move versus saving or applying one.

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 safety profile is covered. The description adds a genuinely non-annotated behavioral fact: existing job copies are preserved after deletion, which is the kind of consequence information an agent needs. It omits auth requirements and what exactly is destroyed beyond the starter itself.

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

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

A single front-loaded sentence with no waste; the resource is stated first and the retention caveat follows. It is appropriately sized for a delete action, though it leaves little room to carry the missing context.

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

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

For a destructive mutation with no output schema and 0% parameter coverage, the description does the minimum: it names the target and one retention guarantee. It does not cover the idempotency/request-id mechanics or the full destruction scope, so it is adequate but clearly incomplete.

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% with three parameters, and the description supplies no parameter meaning at all. The required starter_id is only obliquely implied by 'starter'; request_id and idempotency_key are completely undocumented in both schema and description, so the description fails to compensate for the coverage gap.

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

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

The description states a specific verb and resource ('Delete an organization starter'), which clearly separates it from read/list/create siblings such as yardstick_automation_starters_create and _list. However, it does not explicitly contrast itself with the other mutation sibling (_apply) or the rules_delete family, so sibling differentiation is only partial.

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 when-to-use guidance, no prerequisites, and no named alternative. The clause 'while keeping existing job copies' hints at the effect versus a fuller removal but does not tell the agent when to choose this tool over starters_apply or rules_delete.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's only addition is that results are organization-scoped and 'saved' starters, which is useful but thin; it says nothing about pagination, result ordering, or volume, which matters for a list tool.

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

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

A single front-loaded sentence with no filler; the resource and scope are stated immediately. Nothing is wasted or redundant.

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, non-destructive list tool whose annotations already cover safety, the definition is minimally adequate. However, with no output schema the description could have characterized the return shape or the concept of a 'starter', and it leaves the undocumented request_id parameter unexplained.

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

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

Schema description coverage is 0% and the single optional parameter (request_id, a correlation token) is undocumented in both schema and description. The description offers no parameter meaning to compensate, leaving the agent without an explanation of what request_id does.

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 (automation starters) scoped to the organization's saved items. It is unambiguous about what the tool returns at a high level, but it does not name or contrast with the obvious siblings (automation_starters_create, _delete, _rename, _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?

There is no guidance on when to use this list versus the other automation_starters_* tools, no prerequisite or scope conditions, and no mention of alternatives. The agent must infer usage entirely.

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 the full safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavioral content by stating the response surfaces step and stage matches plus unmatched rules, but it stops short of describing the preview's shape or its bearing on a subsequent apply.

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

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

A single front-loaded sentence with no filler; the verb and scope arrive immediately. It is efficient, though its brevity is achieved partly by omitting needed detail rather than by tight editing.

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 five parameters at 0% schema coverage, nested objects, and no output schema, the description is thin: it never explains the preview payload, the effect of 'matches', or how the result feeds the apply step. An agent can guess it is safe and non-mutating from annotations but cannot confidently construct a correct call or interpret 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% across 5 parameters, including a nested 'source' object and a nested 'matches' object, so the description carries the full documentation burden. It only obliquely hints at the concept behind 'matches' ('step and stage matches and unmatched rules') and says nothing about job_id, source.type/id, request_id, or source_digest, leaving the required source discriminator (starter vs job) unexplained.

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

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

States a specific verb (preview copying) and resource (a starter's or job's rules), which is far better than a tautology. It does not, however, name or contrast itself with the obvious sibling yardstick_automation_starters_apply (or the rules_copy/preview family), so the agent must infer the preview-vs-apply relationship from the name alone.

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 'Preview' implies this is the non-mutating dry-run that precedes an apply, but the description never states when to use it versus yardstick_automation_starters_apply or which situation (template vs. existing job) calls for a preview. Usage is only implied, not instructed.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description usefully adds that renaming does not propagate to existing job copies, which is real behavioral context the annotations cannot express, but it says nothing about the idempotency/request-id replay semantics implied by 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?

A single sentence with the action front-loaded and zero filler. Nothing could be removed without losing 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?

For a mutation tool with zero schema description coverage and no output schema, one sentence is thin. It leaves unanswered what happens on success, how request_id/idempotency_key govern retries, and whether the rename is reversible or rejected on partial matches.

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% across four parameters, and the description contributes nothing about any of them. Names like starter_id and name are self-explanatory, but request_id and idempotency_key carry replay/deduplication semantics that are never explained here or 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?

States a specific verb (Rename) and resource (organization starter) and adds a scope qualifier ('without changing existing job copies') that separates it from other starter mutations. It does not name any sibling explicitly, but the verb-resource pairing is unambiguous against create/delete/apply/save_job.

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 when-to-use guidance, no prerequisites, and no reference to alternatives such as yardstick_automation_starters_create or save_job. The only routing hint is the implicit contrast with operations that do copy jobs, which is a side effect of the scope note rather than deliberate 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 declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description only needs to add context. It adds none: it does not say whether an existing starter with the same name is overwritten, what permissions are required, or how the request_id/idempotency_key params behave.

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

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

A single front-loaded sentence with zero filler; the core action and the object are stated 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 mutation tool with 0% schema description coverage and no output schema, the single sentence is thin. It omits collision/overwrite behavior, auth needs, and the meaning of the two optional control parameters, which an agent needs before invoking 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 must carry the burden. It only implicitly maps to job_id ('a job's') and name ('named'), and says nothing about request_id or idempotency_key, leaving half the parameters undocumented in both schema and prose.

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

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

States a specific verb (save) and resource (a job's automation rules) and names the output artifact (a named organization starter), which is distinguishable from sibling automation_starters_create. However it does not explicitly contrast itself with the create/apply siblings to remove all 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?

There is no when-to-use or when-not-to-use guidance. It never explains how this differs from yardstick_automation_starters_create (build a starter from scratch) or yardstick_automation_starters_apply, leaving the agent to infer the 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 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.