rhizome-mcp

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the context that this operation is append-only and preserves history, which is useful but not comprehensive—it does not explain idempotency behavior or potential side effects beyond the annotation hints.

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 redundant filler. Every word contributes to the core purpose and behavior.

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 captures the primary use case but is thin given the tool has 5 parameters and an output schema. It does not address project_ref routing, idempotency key usage, or content semantics, though output schema reduces the need to explain return values.

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 60%, with content and idempotency_key lacking descriptions. The tool description does not explicitly describe any parameters, only vaguely referring to content as 'collaboration context.' It adds no meaningful clarification beyond the schema.

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

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

The description uses a specific verb ('Append') and resource ('collaboration context to an issue') plus a distinguishing qualifier ('without rewriting history'). This clearly separates it from siblings like update_issue or create_issue.

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 rewriting history' implies this tool is for additive context rather than editing, but no explicit when-to-use or alternative tools are named. Usage guidance is only implied, not directly 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 destructive and idempotent behavior. The description adds useful context beyond that by specifying a precondition ('validated') and a restriction ('empty destination'), giving the agent a clearer model of the operation's impact. No contradiction with annotations.

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

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

A single, tightly worded sentence effectively conveys the core purpose without redundancy. Every word contributes meaning, making it appropriately sized and front-loaded.

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

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

Given the 4-parameter complexity and the presence of an output schema, the description provides the minimum essential context but omits key operational details such as the exact effect of the apply operation and how parameters relate. It is adequate but leaves notable 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 only 50%, with document and source_uri lacking descriptions. The tool description does not elaborate on any parameter meanings, failing to compensate for the coverage gap. It leaves half the parameters semantically 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 'Apply' and clearly identifies the resource ('validated logical project import document') and target ('empty destination'). It distinguishes this tool from siblings like validate_import and export_project by focusing on applying a validated document.

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 'validated' and 'empty destination' provides clear context for when to use the tool, implying it should follow validation and target an empty project. However, it does not explicitly mention alternatives or exclusions, such as using validate_import first or not applying to non-empty destinations.

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 non-readOnly, destructive, and idempotent. The description adds atomicity (all-or-nothing) which is useful context beyond annotations. It does not contradict annotations, but it does not explain the nature of the destructive effects or behavior on invalid plans.

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 wasted words. It delivers the core action and scope efficiently, though it could be slightly longer to include usage 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?

Given the tool's complexity (six parameters, three array types, and atomic semantics), a one-sentence description is inadequate. It lacks critical context about what constitutes a valid plan, how atomicity behaves on failure, what the output schema contains, and its relationship to validate_issue_plan.

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 schema description coverage at only 33%, the description should compensate for the core array parameters (issues, decisions, relations) and idempotency_key. It only names the resources without elaborating on structure, ref usage, or how they interrelate, leaving the schema field names as the primary guide.

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

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

The description clearly identifies the action (create) and the resources (issues, relations, decisions) with the atomicity qualifier. It distinguishes itself from single-entity tools like create_issue, though it does not explicitly name them.

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

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

The phrase 'from a valid plan' implies a prerequisite of validation, but there is no explicit guidance on when to use this tool versus alternatives like apply_import or create_issue. No exclusions or alternative references are provided.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds valuable context: 'history remains available' clarifies that the archive is non-deleting and preserves data, and 'using its current version' reveals the requirement for a matching expected_version. This goes beyond annotation coverage without contradicting it.

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 (8 words) that is front-loaded with the core purpose and contains no filler. Every clause adds meaningful information.

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

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

Given the output schema and annotations, the description covers the core purpose, a key behavioral trait (history retention), and the concurrency condition. It does not elaborate on usage context or all parameter semantics, but for a single-issue archive operation with structured schema, it is 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 descriptions cover issue_id and project_ref, but not the remaining four parameters. The phrase 'using its current version' directly explains the purpose of expected_version, adding meaning not in the schema. However, other parameters like view, idempotency_key, and agent_session_handle remain unexplained, so the description only partially compensates for the 50% schema coverage.

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

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

The description clearly states the action ('Archive one issue') with a specific verb and resource, and adds 'using its current version' which indicates the optimistic concurrency scope. This distinguishes it from sibling tools like update_issue or get_issue.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention conditions such as issue state or permissions. The only implicit usage cue is the word 'Archive', which is not enough to differentiate from other issue-management actions.

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 concurrency semantics with 'using its current version,' indicating optimistic locking via expected_version. This goes beyond the annotations, which already declare destructive and idempotent behavior, providing valuable context for invocation.

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 leads with the action and includes all essential constraints. No extraneous words or repetition of schema details.

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

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

For a destructive tool with an output schema, the description covers the core behavior, state constraints, and concurrency mechanism. It doesn't detail error handling on version mismatch, but the output schema likely covers that. Overall, adequate 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?

The schema documents 3 of 4 parameters, but expected_version lacks a description. The description's 'current version' clarifies expected_version's role, and 'open or claimed' gives context for review_request_id. This compensates for the missing schema detail.

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 ('cancel') and resource ('review request'), and specifies scope ('open or claimed'). This clearly distinguishes it from sibling tools like replace_review_request and supersede_review_request.

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 by limiting cancellation to open or claimed requests, but doesn't explicitly mention alternatives or exclusions. This is sufficient guidance for selecting the tool when cancellation is intended.

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

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

The description discloses key behavioral traits: atomicity, exclusivity, lease duration range (60-3600s), renewability, failure on already claimed work, and idempotent retry replay. These go well beyond the annotations (which only state readOnlyHint=false, idempotentHint=true) and provide essential operational context.

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

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

The description is a single sentence packed with relevant technical detail—atomic acquire, exclusive ready/review work, lease range, renewal, failure case, and idempotent retry. There is no redundant or filler content; every phrase earns its place.

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

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

The description covers the core behavioral contract thoroughly, including atomicity, exclusivity, lease mechanics, and retry semantics. It does not explain when to use this tool relative to siblings, but with an output schema present and strong schema coverage, the missing piece is acceptable. The description is complete for the tool's complexity.

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

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

The input schema has 100% parameter coverage, so the baseline is 3. The description adds minimal extra semantic value: it mentions lease duration and keyed retries, but these largely echo the schema descriptions for lease_seconds and idempotency_key. No new parameter-level meaning is introduced.

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 atomically acquires exclusive ready/review work with a renewable lease. It distinguishes this from sibling actions like get_issue (read-only) and update_issue (modification). The verb 'acquire' and specific object 'exclusive ready/review work' make the purpose unambiguous.

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

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

The description implies usage for claiming an issue when starting work, but it does not explicitly state when to use this tool versus alternatives like renew_attempt or get_work_context. No exclusions or alternative recommendations are provided; usage context is inferred rather than explicit.

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

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

The description discloses key behavioral traits: writes a new session on every call (non-idempotent) and produces an unrecoverable handle. This goes beyond the annotations, which only indicate idempotentHint false, by explaining the practical consequence (a new session each time) and the risk of losing the handle. It does not cover all side effects, but adds meaningful context.

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

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

A single, well-structured sentence that front-loads the core action and includes critical behavioral nuance (non-idempotent, unrecoverable handle). Every clause earns its place, with no redundancy or filler.

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

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

Given the presence of an output schema and full parameter coverage, the description provides sufficient context for the tool's core function and side effects. It could be slightly more complete by mentioning the relationship to sibling tools or typical usage flow, but it is not incomplete for the tool's complexity.

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

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

All six parameters have descriptions in the schema (100% coverage), so the schema already documents each field. The tool description itself does not add extra semantic value about parameters, such as relationships or usage tips. This matches the baseline for full schema coverage.

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

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

The description states the tool creates a durable attribution session and an unrecoverable handle, which is a specific action on a clear resource. However, it does not explicitly differentiate from sibling tools like end_agent_session or open_project, though the name and action make the purpose largely unambiguous.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, such as mentioning it as a prerequisite for other agent actions or that end_agent_session is the counterpart. The only implied usage is that creating a session is needed for attribution, but no direct context or exclusions are 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 indicate this is a mutation (readOnlyHint=false) and not idempotent (idempotentHint=false), which provides some baseline. The description adds that the tool can create different issue types and optionally set hierarchy and labels, giving more specific behavioral context than annotations alone. However, it does not disclose return values, permissions, or side effects beyond the obvious creation.

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

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

The description is a single, front-loaded sentence that uses every word to convey meaning. It is concise, non-redundant, and avoids filler content, making it efficient for an agent to parse.

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?

Despite having an output schema that covers return values, the tool is complex with 14 parameters and low schema coverage. The minimal description fails to convey important parameter semantics, usage nuances, or typical scenarios, making it incomplete for an agent to invoke correctly without additional inference.

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

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

With only 21% schema description coverage, the burden falls on the description to explain parameters. It clarifies that 'epic, task, or bug' corresponds to the 'type' parameter, and 'hierarchy'/'labels' hint at parent_issue_id and label-related parameters. The remaining 11 parameters (e.g., view, status, priority, description, blocked_reason, idempotency_key) are not covered, leaving significant ambiguity for the agent.

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

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

The description clearly states the verb ('Create') and resource ('one epic, task, or bug'), and scopes it with optional hierarchy and labels. This distinguishes it from sibling tools like update_issue, get_issue, and apply_issue_plan, which all have different actions or scopes.

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

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

The description implies usage for creating a single issue of a specified type, but does not explicitly state when to use this tool versus alternatives like update_issue for modifications or apply_issue_plan for applying plans. No exclusions or prerequises are mentioned, leaving the agent to infer context from the name and siblings.

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 do not provide read-only, idempotency, or destructive hints (all false). The description adds deprecation status and the 'exact' requirement, but does not disclose side effects, auth needs, or failure modes. It carries some burden, but not enough to exceed a baseline adequate score.

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 action and deprecation notice. Every word earns its place with zero waste.

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

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

With an output schema present and a clear deprecation message, the description is largely sufficient. It lacks detailed behavioral caveats, but for a deprecated create tool, the provided context plus sibling list allows an agent to invoke it correctly. Not a 5 because it omits any mention of prerequisites or side effects beyond 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 coverage is 57%, and several required parameters (target_issue_version, target_event_id, artifact_ids) lack schema descriptions. The description clarifies these as 'exact issue version, event position, and artifact set,' adding meaning beyond the schema. It does not explain all 7 parameters, but it adds significant value for the core ones.

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 ('Create') and resource ('review request') with precise scope ('exact issue version, event position, and artifact set'). It clearly distinguishes from siblings by noting deprecation and pointing to replace_review_request as the preferred 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?

Explicitly states 'Deprecated: prefer replace_review_request,' providing a direct alternative and when-not-to-use guidance. This is a clear exclusion that helps the agent choose the correct sibling 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?

Annotations indicate idempotent and non-readonly. The description adds that the handle must be 'explicitly created durable', which narrows the accepted input, but doesn't disclose side effects or error behavior beyond that.

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

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

A single sentence with no redundant words, but the phrasing is slightly awkward. It is appropriately short for the tool's simplicity.

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 an output schema and annotations, the description is acceptable but lacks usage context and does not mention when to pass project_ref or omit it. The tool's simplicity helps, but guidelines are 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?

The schema documents project_ref but not agent_session_handle; the description identifies the handle as the target and specifies it must be an explicitly created durable session handle, adding some meaning. However, it doesn't explain how to obtain one or interaction with project_ref.

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

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

The description uses the verb 'End' with the resource 'agent session handle', and adds 'explicitly created durable' to distinguish from implicit or temporary sessions. However, it doesn't contrast with sibling tools like create_agent_session or finish_attempt, but the verb and resource are clear.

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

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

No statement about when to use this tool versus alternatives, no exclusions or prerequisites. The description only states what it does, not when it should be chosen.

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 that the output is a 'logical interchange document', but it does not explain behavioral aspects like how the 'delivery' parameter affects output, side effects (though none due to annotations), or whether it requires an explicit project_ref. It adds minimal context beyond annotations, hence a mid-range score.

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 wasted words. It immediately communicates the tool's primary action and output format.

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?

Annotations and output schema cover safety and return format, reducing the burden on the description. However, the description is too terse to provide complete guidance: it lacks usage context, alternative differentiation, and parameter behavior. For a simple export tool, it is minimally adequate but leaves gaps in when and how to use it.

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

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

The description does not add any meaning to the parameters beyond the schema. Schema coverage is 67%, leaving the 'delivery' parameter (enum: artifact/inline) undocumented in both schema and description. The description fails to clarify what 'delivery' means or how it influences the export, and it does not compensate for the lack of parameter detail.

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 ('Export'), the resource ('the selected project'), and the output format ('version 1 logical interchange document'). This distinguishes it from sibling tools like get_project or get_changes, which retrieve different data shapes.

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 does not mention prerequisites (e.g., needing an open project), exclusions, or why one might choose export_project over get_project. The description only states what it does, not when to invoke it.

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

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

Annotations already mark this as destructive, non-read-only, and idempotent. The description adds no additional behavioral context such as irreversibility, authorization requirements, or side effects beyond the word 'End'.

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 fluff, but it is under-specified for an 18-parameter tool. It is easy to parse but sacrifices critical 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 tool with 18 parameters and low schema coverage, the description does not provide enough context about required inputs, state transitions, or side effects. It is not sufficient for reliable tool selection and invocation.

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

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

Schema description coverage is only 11%, leaving most parameters unexplained. The description mentions outcome, verification, artifacts, and status, but omits the required fields attempt_id, lease_token, and result_summary, leaving agents without enough semantics to construct valid calls.

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

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

The description uses the specific verb 'End' and names the resource 'leased attempt', making its function clear. It lists core data (outcome, verification, artifacts, status), distinguishing it from sibling tools like renew_attempt or save_attempt_note.

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 guidance on when to use this tool versus renew_attempt or other attempt-management siblings. The context of ending a leased attempt is implied, but no exclusions or alternative recommendations are 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, and destructiveHint=false, covering safety. The description adds that events are ordered and that fetching starts after a given event ID, which is useful but not extensive behavior detail. It does not mention pagination or how filters interact, so it provides a moderate amount of additional transparency.

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

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

The description is a single, concise sentence that front-loads the verb and key qualifier. Every word contributes to the meaning, and there is no redundancy or filler.

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

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

Given 6 parameters (3 undocumented), moderate complexity, and available annotations/output schema, the description is terse. It does not explain the relationship between limit, event_types, and the event ordering, nor how to handle subsequent pages. However, the output schema and annotations reduce the need for return-value explanation, making it minimally complete for a read-only sync endpoint.

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

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

Schema description coverage is 50%: issue_id, project_ref, and agent_session_handle are described in the schema, while limit, event_types, and since_event_id are not. The description references 'event ID' which helps clarify since_event_id but does not elaborate on limit or event_types. This adds some meaning but does not fully compensate for the undocumented 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 the action ('Get'), the resource ('ordered issue events'), and the specific scope ('after an event ID for incremental synchronization'). This distinctly differentiates the tool from siblings like get_issue_activity by emphasizing incremental sync and event ordering.

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

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

The description gives a clear usage context ('for incremental synchronization'), which implies when to use it. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'current' state nuance, suggesting the latest version, but does not disclose additional behavioral traits such as error handling or return format. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with zero waste. It clearly communicates the verb, resource, and identifier formats without extraneous detail, earning its place.

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

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

Given the tool's simplicity and the presence of an output schema, the description is largely complete. However, it omits any mention of the 'view' parameter, whose enum values (compact/standard/full) may imply different response depths, and it does not clarify the behavior of 'current' in terms of versioning or archived issues. This leaves a minor but notable 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 coverage is high (75%), setting the baseline at 3. The description reinforces issue_id semantics by naming the identifier formats, but it does not explain the 'view' parameter (which lacks a schema description) or add meaning for project_ref and agent_session_handle beyond what the schema provides.

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

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

The description uses the specific verb 'Get' with resource 'current issue record' and identifiers 'ULID or ISSUE-N display ID', clearly distinguishing it from siblings like get_issue_graph (graph) and list_issues (list). It leaves no doubt about the tool's primary function.

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

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

The description implies usage for fetching a single issue by its identifier, but it does not explicitly state when to use this tool versus alternatives. No exclusions or sibling tool references are provided, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds useful behavioral details: results are newest-first and unified/aggregated. It does not, however, disclose pagination behavior or filtering implications.

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 verb and object. No wasted words.

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

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

For a read-only activity tool with an output schema, the description is adequate but not complete: it does not mention the configurable types filter or the cursor-based pagination, and it lacks usage context vis-à-vis sibling tools. The presence of an output schema mitigates the need to describe return values, but filtering options are central to the tool's 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 43% – only issue_id and project_ref are described in the schema. The tool description adds no parameter information, leaving limit, order, types, cursor, and agent_session_handle without additional context. Since coverage is low, the description fails to compensate for undocumented 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 uses the specific verb 'Get' and defines the resource as a 'unified newest-first timeline of issue work and artifacts,' clearly distinguishing it from siblings like get_issue (which likely returns issue state) and get_changes (which may return diffs).

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 over alternatives; it only implies its use for an activity timeline. No alternatives or exclusions are mentioned, though the 'unified' phrasing hints it aggregates multiple sources.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds 'bounded' and 'hierarchy', which provide useful context about the graph's scope, but it does not explain traversal behavior, limits, or return format beyond what annotations/schema offer.

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. It conveys the essential purpose 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?

Given the tool's complexity (10 parameters, output schema, annotations), the description is minimally viable but lacks explicit guidance on when to use it versus siblings. The output schema covers return values, but overall context could be richer.

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

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

Schema description coverage is 100%, so the schema fully documents all 10 parameters. The description adds no parameter-specific meaning, but the baseline of 3 is appropriate since the schema carries the burden.

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 ('Get'), names the resource ('relation and hierarchy graph'), and scopes it to 'around one issue' and 'bounded', which distinguishes it from siblings like get_issue (single issue) and get_planning_graph (planning graph). This is a clear statement of purpose.

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

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

The description implies usage through the phrase 'around one issue', indicating the tool is for exploring a single issue's relations and hierarchy. However, it does not explicitly state when to use this over alternatives (e.g., get_planning_graph) or provide exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context by explaining that the graph is dependency-aware and focuses on entry points and blocking nodes, which goes beyond the structured 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 wasted words. It efficiently communicates the tool's core purpose and output.

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 output schema covers return values, so lack of return-value description is acceptable. However, with 7 optional parameters and low schema coverage, the description leaves significant gaps about parameter usage and when to invoke this tool, making it only partially complete for reliable invocation.

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

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

Schema description coverage is only 43%, and the description does not compensate by explaining the key parameters: depth, max_nodes, include_review, and include_related. These remain ambiguous, and the description provides no additional semantic guidance beyond the sparse schema descriptions.

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

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

The description clearly states the tool gets dependency-aware entry points and blocking nodes, naming the specific resource (planning graph) and its purpose (work selection). This differentiates it from siblings like get_issue_graph and get_work_context, which focus on different aspects.

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 work selection' implies a use case but does not explicitly state when to use this tool over alternatives, nor does it provide exclusions. The agent must infer the appropriate context from the tool name and description 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds the fallback to a configured default and lists specific data categories, but does not disclose additional behavioral traits like authentication requirements or potential errors.

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

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

A single sentence that is front-loaded with the action and clearly enumerates the data categories. No filler or redundant information.

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

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

Given the tool has an output schema, rich annotations, and a clear purpose, the description suffices for selecting and invoking the tool. However, the meaning of 'event position' and the include_instructions parameter are left undefined, leaving minor gaps.

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

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

Schema descriptions cover 67% of parameters, with project_ref and agent_session_handle well documented. The tool description echoes project_ref but does not clarify the undocumented include_instructions parameter, so it adds minimal value beyond the schema.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource as project metadata, limits, supported values, event position, and guide links. It distinguishes from sibling tools like get_issue or get_issue_graph by focusing on project-level information.

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

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

The description clearly implies when to use this tool (when you need project metadata) and mentions the fallback to a configured default, providing useful context. However, it does not explicitly compare to alternatives or state when not to use it.

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

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

Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context (e.g., what happens if the ID is not found, any rate limits, or prerequisites). Since annotations carry the transparency burden, a baseline score of 3 is appropriate.

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

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

The description is a single sentence, 8 words, and front-loads the core action ('Get one review request'). Every word is necessary and there is no fluff or redundancy.

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

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

For a simple get-by-id tool, the combination of a clear description, complete schema descriptions, rich annotations, and an output schema is largely sufficient. The only minor gap is the lack of explicit guidance about when to favor this over list_review_requests, but the schema and annotations cover the essential invocation details.

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

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

Schema coverage is 100%, with all three parameters having descriptions (e.g., review_request_id as 'Canonical review request identifier (ULID)'). The description itself adds minimal parameter meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description 'Get one review request by identifier' clearly states a specific verb (get), a specific resource (review request), and a specific scope (one by identifier). It distinguishes from siblings like list_review_requests (which retrieves multiple) and create/cancel/replace_review_request (which are mutations).

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

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

The description implies usage (when you need a single review request by ID) but does not explicitly state when to use it versus alternatives such as list_review_requests. No exclusions or alternative tool names are mentioned. The schema provides some routing context (project_ref) but that is not part of the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'bounded' trait, indicating results are limited, but does not specify how bounds work (e.g., default limits, configurable via the limits parameter) or mention the 'include' parameter's role in selecting sections. This adds minimal behavioral context 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: 'Get bounded task, blocker, decision, checkpoint, and recovery context.' It is front-loaded with the verb and resource, and every word carries meaning. This is concise and well-structured.

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

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

The tool is a read operation with a rich schema (5 parameters, nested limits object, include enum) and an output schema. The description provides the high-level purpose, and the schema already documents details like default behavior and parameter constraints. Given the annotation coverage and schema richness, the description is sufficiently complete for an agent to select the tool correctly, even though it does not mention integration points like project_ref or agent_session_handle.

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

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

The input schema has 100% coverage with descriptions for all parameters (e.g., issue_id: 'Issue whose work context to load', include: 'Optional unique context sections; empty returns the compact default'). The description's list of context types (task, blocker, decision, checkpoint, recovery) loosely maps to schema enum values but does not add further parameter-level detail. Since the schema handles parameter semantics comprehensively, a baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Get' and a resource 'work context' with a 'bounded' qualifier, enumerating the context types (task, blocker, decision, checkpoint, recovery). This clearly indicates the tool's purpose and distinguishes it from siblings like 'get_issue' by focusing on a bounded aggregate view, though it does not explicitly mention aggregation or a composite nature.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or alternative tools, and there is no contextual hint about appropriate use cases. The list of context types implicitly suggests a holistic view, but this is not explicit enough to count as usage guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds useful behavioral details about cursor pagination and the ability to scope results project-wide or by issue, which are not captured by 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 that is front-loaded with the verb 'List' and communicates scope and pagination without waste. Every word earns its place.

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

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

For a simple list tool with strong annotations, a descriptive schema, and an output schema, this description covers the essentials: what it lists, the optional scoping, and pagination behavior. No additional context is strictly necessary.

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

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

Schema descriptions cover 4 of 5 parameters. The description adds meaning to the cursor parameter by explicitly mentioning 'cursor pagination', which is the one parameter lacking a schema description. This slightly elevates it above the baseline.

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

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

The description clearly states it lists decisions and specifies both scoping options (project-wide or issue-scoped) and the pagination mechanism. This distinguishes it from sibling tools like list_issues or get_issue_activity, which operate on different resources.

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 the tool: to list decisions, optionally scoped by issue. It doesn't explicitly name alternative tools or exclusion criteria, but the context is sufficient for an agent to choose this over list_issues or similar list 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 and destructiveHint=false, so the agent knows it is safe. The description adds the 'effective status, blockers, claimability' context, but it does not disclose pagination behavior, defaults for archived issues, or any other non-obvious behavior. This is adequate but not enriching.

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, concise sentence that is front-loaded with the verb and resource, and delivers relevant specifics without waste.

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

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

Given the tool's complexity (14 parameters, output schema), the description covers the core purpose but omits important operational details such as project_ref scoping, pagination defaults, and whether archived issues are excluded by default. The annotations and output schema reduce the burden, but this is not complete enough for an agent to make fully informed decisions on all variations.

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 29%, so the description carries some responsibility. It hints at filterable dimensions (effective_statuses, is_blocked, is_claimable) but does not elaborate on many other parameters like statuses, labels, or priorities, nor does it distinguish 'statuses' from 'effective_statuses'. This adds a bit of meaning but does not fully compensate for 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 clearly states the tool lists and filters issues, with specific mention of effective status, blockers, and claimability. This distinguishes it from single-issue retrieval (get_issue) and search. However, it does not explicitly name alternatives, 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 implies use for listing/filtering issues, which is clear. It does not explicitly state when-not-to-use or mention alternatives like get_issue for single issues, but the context is unambiguous given the tool name and sibling set.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat safety traits. It adds behavioral context by explicitly mentioning cursor pagination and optional name search, which informs the agent about iteration and filtering behavior. 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, front-loaded sentence: 'List reusable labels with optional name search and cursor pagination.' Every word is necessary and adds distinct value, with zero redundancy or filler.

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

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

The tool is a simple read-only list operation with an output schema available. The description covers the core action, search, and pagination. It does not describe return values, but the output schema handles that, and annotations provide safety context. Reasonably complete for its complexity.

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

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

Schema descriptions cover limit, project_ref, and agent_session_handle, but query and cursor have no descriptions. The description's 'name search' maps to query and 'cursor pagination' maps to cursor, compensating for the undocumented parameters. This adds semantic meaning beyond the schema, though it does not parse the exact syntax for query.

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

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

Description starts with the specific verb 'List' and resource 'reusable labels', making the primary action unambiguous. It further differentiates from sibling list_* tools by mentioning optional name search and cursor pagination, which are unique capabilities for this tool.

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

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

The description implies the tool is for retrieving labels, with optional name filtering and pagination. Although it does not explicitly list alternatives or exclusions, the resource-specific wording ('reusable labels') makes the use case clear. It provides enough context for an agent to choose this tool when labels are involved.

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 safety behavior. The description does not contradict these but also adds little beyond the filter capability. Pagination behavior (e.g., cursor, default limit) is not described in the description, though the output schema and parameter descriptions partially cover this.

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

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

The description is a single sentence that is front-loaded with the core action ('List review requests') and adds only relevant filter details. Every word contributes value, with no redundancy or extraneous 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?

The tool has a rich output schema and strong annotations, so the description does not need to explain return values or safety. However, with 6 parameters and a pagination cursor, the description could have provided more context on pagination or when to use this over search. It is minimally adequate but leaves some usage nuances implicit.

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 schema coverage at 50%, the description partially compensates by explicitly naming 'status' and 'claimability' as filters, clarifying their role. However, it does not explain cursor or how pagination works, and the three parameters with schema descriptions (limit, project_ref, agent_session_handle) are not enriched further.

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

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

The description uses the specific verb 'List' with the resource 'review requests' and specifies optional status and claimability filters. This clearly distinguishes it from sibling tools like get_review_request (single item) and mutation tools such as create/cancel/supersede_review_request.

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

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

The description implies usage for listing review requests with filters but provides no explicit guidance on when to use this tool versus alternatives like search or get_review_request. No exclusions or preferred contexts are stated, leaving usage to be inferred from the tool's name and sibling names.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description reinforces this with 'add or remove.' It adds specific relation types and the single-relation scope, but does not elaborate on irreversible removal or other behavioral nuances. This adds some value beyond annotations without fully disclosing consequences.

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

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

The description is a single, efficient sentence that immediately states the core action and relation types. No wasted words; it is appropriately front-loaded and easy to parse.

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?

Despite having an output schema, the tool is a destructive write operation with 7 parameters and clear potential for misuse (e.g., removing relations permanently). The sparse one-liner fails to provide sufficient context regarding relation direction, idempotency behavior, or error conditions, making it incomplete for safe invocation.

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

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

The schema covers 57% of parameters, but the description does not compensate for the undocumented ones. It does not clarify the roles of source_issue_id versus target_issue_id in the relation, nor explain the idempotency_key or agent_session_handle. The assertion 'one relation' implies a single pair, but key parameter semantics are left ambiguous.

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

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

The description explicitly states 'Add or remove one blocks, related_to, or duplicates relation,' which clearly identifies the verb (add/remove), the resource (issue relations), and the specific relation types. This distinguishes it from sibling tools like get_issue_graph (read-only) and update_issue (broader updates).

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites, context, or exclusions. It is a bare functional statement with no usage 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 annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds value by listing the exact return contents (project_ref, metadata, limits, etc.), which helps the agent anticipate the output. No contradictions with 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, dense sentence that conveys the action and the full set of returned items without extraneous words. Every phrase earns its place, making it highly efficient.

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

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

Given the tool's simplicity (one parameter, read-only semantics, output schema provided), the description adequately covers the tool's behavior and expected output. It lacks usage guidance against siblings, but that is a separate dimension and not critical for understanding this tool's core function.

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

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

The schema provides only a 'project_root' string parameter with no description. The description clarifies that it must be an absolute root path, adding semantic meaning beyond the schema's bare type. It does not provide examples or path format details, but for a single parameter this is adequate.

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 'Open' and identifies the resource 'project by absolute root,' enumerating the returned fields (project_ref, metadata, limits, supported values, event position, guide links). This makes the tool's purpose clear and distinguishes it from siblings like get_project by specifying the absolute root requirement and the detailed return payload.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_project or export_project. It does not state prerequisites, exclusions, or alternative recommendations, leaving the agent to infer usage from the tool's 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 indicate destructiveHint=true, and the description adds 'durable' and 'superseding' context, hinting at the effect on an existing decision. However, it does not disclose side effects like how the superseded decision's status changes or any permissions needed. The description is consistent with annotations but adds limited behavioral detail.

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, front-loaded with the action verb, and contains no unnecessary words. It efficiently conveys the core function and a key optional behavior.

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 has 8 parameters, a status enum, and an output schema, the description captures the primary purpose but omits details such as how to set status to 'rejected', how linking to issues/projects works, and how supersession is reflected. It is adequate for a simple write operation but leaves gaps for a tool of this complexity.

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

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

With only 25% schema description coverage, the description should compensate by explaining parameter roles. It vaguely hints at issue_id/project_ref via 'project or issue decision' and supersedes_id/status via 'superseding', but it does not clarify which parameters are required, how they relate, or the meaning of the status enum. This is insufficient for effective 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 uses a specific verb 'Append' and clearly identifies the resource as a 'durable project or issue decision', also noting the optional superseding behavior. This distinguishes it from siblings like add_comment or list_decisions, making the tool's purpose unambiguous.

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

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

The description implies the tool is for recording formal decisions, but it does not explicitly state when to use it over alternatives (e.g., add_comment for comments) or provide exclusion criteria. The use case is clear enough for basic selection, but there is no explicit 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 indicate this is a non-read-only, non-idempotent operation. The description adds the 'active' and 'before it expires' constraints, but does not disclose side effects such as whether the lease token rotates, how lease_seconds changes the lease, or any rate limits. It adds some context beyond annotations but omits potentially important behavioral details.

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

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

The description is a single, front-loaded sentence with a clear verb and object. It is concise and contains no redundant words, examples, 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?

With an output schema present, return values do not need to be explained. However, the description leaves gaps around the lease_token and lease_seconds parameters, and does not clarify what 'active work or review lease' means in terms of the attempt lifecycle. It is minimally adequate but lacks important operational 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 only 40%, and the description provides no parameter-specific details. The required parameters attempt_id and lease_token are not explained, and the optional lease_seconds behavior is not mentioned. The description does not compensate for the low schema coverage.

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

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

The description uses the specific verb 'Extend' and names the resource 'active work or review lease', clearly distinguishing it from siblings like 'finish_attempt' and 'create_review_request'. It states exactly what action the tool performs.

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 'before it expires' provides clear temporal context for when to use this tool: on an active lease that is about to lapse. It does not explicitly name alternatives or exclusions, but the timing guidance is sufficient for most 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 indicate destructive and non-read-only behavior. The description adds valuable context about atomicity and transactional semantics, which goes beyond annotations. It does not detail additional side effects or permissions, but the atomicity disclosure is a meaningful addition.

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 waste. It clearly conveys the core action and key attribute (atomicity) in an efficient manner.

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 operation with 8 parameters and low schema coverage, the description is insufficient. It does not explain preconditions, effects on the predecessor, or parameter relationships. Although an output schema exists, the operational context remains 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 only 38%, and the description itself mentions no parameters. The tool has 8 parameters with 5 required, and no guidance is provided on their semantics or relationships. This leaves the agent with insufficient information to correctly populate required fields like 'predecessor_expected_version' or 'target_issue_version'.

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

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

The description clearly states the tool's function: to atomically supersede a predecessor review request and create its open successor. It uses specific verbs and resources, but does not explicitly differentiate from the sibling tool 'supersede_review_request', which may cause 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?

The phrase 'in one transaction' implies usage where atomicity is required, and the predecessor/successor relationship gives some context. However, there is no explicit guidance on when to use this tool versus alternatives like 'supersede_review_request' or 'create_review_request', leaving the agent to infer.

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

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

Annotations already indicate a write operation (readOnlyHint: false) but provide no additional detail. The description adds only the ambiguous word 'restartable', which may hint at checkpointing but is not explained. It does not mention the required lease_token proof, potential side effects, or any idempotency nuances (despite the idempotency_key parameter). This leaves significant behavioral gaps.

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 and is very concise with no filler. It front-loads the action. However, 'restartable' is unclear and might mislead; a slightly more explicit phrase like 'save an attempt note that can be used to resume work' would be both concise and clearer. Still, it earns a high score for structure.

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

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

For a tool with 10 parameters including sensitive auth fields (lease_token), idempotency control, and an enum, the description is too thin. It does not explain the lease requirement, the meaning of 'restartable', or how the different note kinds should be used. The output schema exists, so return values are not necessary, but the high-level 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 100%, so the schema itself documents all parameters with descriptions. The tool description adds no parameter-specific meaning beyond 'restartable', which does not map to any one schema field. The baseline of 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the verb ('Append'), the resource (a note to an attempt), and the scope (checkpoint, finding, warning, or progress). It distinguishes from sibling tools like add_comment or record_decision by referencing attempt-specific notes. Though 'restartable' is slightly vague, the core purpose 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., active attempt lease), when to choose 'checkpoint' vs 'progress', or situations where another tool like record_decision might be more appropriate. The description is a bare statement with no exclusions or contextual hints.

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 meaningful behavioral context beyond the annotations: it discloses a default limit of 20, that archived records are excluded by default, and that results are relevance ordered. These details help the agent anticipate behavior without contradicting the read-only and idempotent hints.

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

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

The description is a single, well-structured sentence that front-loads the primary purpose ('Full-text search') and packs four key behavioral details into concise clauses. No words are wasted, and every element earns its place.

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

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

Given the tool's complexity (12 parameters) and the presence of a rich schema and annotations, the description covers the core behavioral defaults (pagination, limit, archived handling, ordering) that aren't obvious from the schema alone. It does not enumerate searchable entity types, but those are documented in the schema's entity_types parameter, and the output schema covers return structure. The description is sufficient for a capable 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?

The schema already covers all parameter descriptions (100% coverage), so the baseline is 3. The description adds extra value by clarifying the default limit (20) and the default behavior for archived records, which directly relate to the limit and include_archived parameters. This helps the agent understand the actual defaults beyond the schema's '0 uses the default' phrasing.

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 'Full-text search,' a specific verb and resource that clearly identifies the tool's function. It immediately distinguishes it from sibling listing tools like list_issues and get_issue by emphasizing text-based search across content. Additional details like cursor pagination and relevance ordering further sharpen the purpose.

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

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

The description implies the tool is for full-text search, but it does not explicitly state when to prefer it over structured list/filter tools like list_issues. There are no named alternatives or exclusions, so the usage guidance is implied rather than explicit.

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

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

While annotations already declare destructiveHint=true and idempotentHint=true, the description adds the important deprecation warning and the concurrency-related detail 'using its current version', which hints at optimistic locking via expected_version. This is meaningful context beyond the structured fields, though it stops short of explaining the exact effects of superseding.

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 only two sentences, front-loading the core action and immediately adding a deprecation note. No redundant information. 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?

With the output schema present and annotations covering safety/idempotency, the description provides sufficient context for a deprecated tool. It mentions the valid target state ('open or claimed') and the version mechanism. However, it does not elaborate on what 'supersede' does to the original request (e.g., whether it becomes closed), which would be helpful but is not critical given the explicit deprecation direction.

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 75%, with expected_version undocumented. The description's phrase 'using its current version' directly clarifies the role of expected_version (the current version to check against). This adds semantic value beyond the schema, while the remaining params are already described.

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

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

The description uses the specific verb 'Supersede' with a clear resource ('an open or claimed review request') and a mechanism ('using its current version'). It also explicitly distinguishes this tool from sibling `replace_review_request` by marking itself as deprecated, which resolves 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?

The description gives an explicit when-to-use context ('open or claimed review request') and directly names an alternative ('prefer replace_review_request'), telling the agent that this tool should not be used in favor of the replacement. This is clear, actionable guidance.

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

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

Annotations already state readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating and potentially destructive operation. The description adds the concurrency-control mechanism (using current version) but does not elaborate on conflict behavior, side effects, or the meaning of idempotentHint. It contributes some value beyond annotations but not extensive detail.

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 conveys the core purpose without waste. Every word earns its place, making it highly concise and well-structured.

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

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

Given the tool's complexity (8 parameters, nested objects, destructive hint, optimistic concurrency), the description is too minimal. It does not explain error handling on version conflict, behavior of create_missing_labels, or how the view parameter affects output. An output schema exists but does not compensate for missing behavioral and parameter 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 only 38%, so the description must compensate for undocumented parameters. It only hints at expected_version ('using its current version'), while other critical parameters like changes, idempotency_key, create_missing_labels, and view remain unexplained. The description adds little to parameter understanding.

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

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

The description clearly states the tool's function: 'Patch one issue using its current version for optimistic concurrency.' It uses a specific verb ('patch'), names the resource ('one issue'), and adds a distinguishing detail (optimistic concurrency) that separates it from sibling tools like create_issue or archive_issue.

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 the tool: when updating an issue with optimistic concurrency, requiring the current version. It does not explicitly list exclusions or alternative tools, but the context is unambiguous enough for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'without writing anything' phrase is largely redundant. The description adds minimal behavioral context beyond what annotations provide, but it does reinforce the non-mutating nature against sibling tools like apply_import.

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 conveys the action and the key constraint without extraneous detail. Every word adds value.

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

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

Given the existence of an output schema and rich annotations, the description does not need to explain return values. However, it does not clarify the purpose of document versus source_uri, which are both optional and undocumented in the schema. This is a notable gap for a validation tool with 4 parameters, though the overall simplicity of the tool mitigates the impact.

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

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

Schema coverage is 50%, with document and source_uri having no descriptions. The tool description does not explain the relationship between these parameters or when to use one over the other. The only parameter guidance comes from the schema for project_ref and agent_session_handle, leaving the core input parameters ambiguously specified.

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

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

The description clearly states the verb 'validate' and the resource 'logical project import document,' while the phrase 'without writing anything' distinguishes it from apply_import and other mutation tools. This is specific and unambiguous.

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

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

The description implies a dry-run validation use case by stating 'without writing anything,' but it does not explicitly mention alternatives or when to avoid using the tool. The context is clear enough for an agent to infer the primary purpose, but lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable context by stating no write occurs, which reinforces the annotation. It also introduces 'normalize', hinting at transformation behavior beyond what annotations cover, though it does not detail normalization rules.

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

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

The description is a single, front-loaded sentence with no filler words. It clearly states the action, object, and key side-effect constraint, making it highly efficient.

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

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

Given the tool's complexity (nested arrays, multiple required parameters) and the existence of an output schema, the description is minimal but adequate. It explains the core purpose and the no-write constraint, but does not elaborate on what 'normalize' entails or what validation criteria are enforced. The annotations and output schema fill some gaps, but not all.

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 33% (only project_ref and agent_session_handle have descriptions). The tool description provides no parameter-level guidance, leaving the agent to infer the meaning of issues, relations, decisions, and include_normalized_plan from names alone. With low coverage, the description needed to compensate but did not.

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

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

The description uses specific verbs ('Normalize and validate') and a clear resource ('bounded multi-issue plan'), and explicitly distinguishes from writing by adding 'without writing it'. This makes the tool's purpose unmistakable and differentiates it from sibling tools like apply_issue_plan.

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 writing it' clearly indicates a read-only validation/preview use case, contrasting with apply_issue_plan. However, it does not explicitly state when to prefer this over validate_import or when not to use it, so it falls just short of full guidance.

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