retasc

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

With no annotations, the description fully carries the burden and does so excellently. It discloses that dependency cycles are rejected, that billing failures produce a tellHuman message, and advises against treating billing failures as healthy session continuations. This is substantial, useful behavioral information beyond what the schema provides.

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

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

The description is front-loaded with the core purpose ('Link two issues'), and every subsequent sentence adds critical operational detail. It is appropriately sized for the complexity of the tool, with no wasted words.

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

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

The description thoroughly covers the exceptional behaviors (cycle rejection, billing refusal) and the dependency graph context, which are the tool's most complex aspects. It does not detail return values, but no output schema is expected. Minor gaps: no clarification of 'related'/'duplicate' semantics or whether the reverse relation is auto-created, but the provided content is substantive enough for most use cases.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the meaning of the 'type' values and their role in the dependency graph, but does not explicitly define the roles of sourceId and targetId (e.g., direction of 'blocks') or the semantics of 'related'/'duplicate'. Some meaning is implied, but gaps remain for a fully parameter-complete 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 action ('Link two issues') and enumerates the allowed relation types, making its purpose unambiguous. It distinguishes itself from sibling tools like remove_relation by focusing on creating links.

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

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

It explains the significance of 'blocks'/'blocked_by' for the dependency graph, giving context for when these types are appropriate. It also provides clear instructions on handling billing refusals (tellHuman), but does not explicitly mention alternatives like remove_relation or specify when NOT to use this tool.

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

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

With no annotations, the description fully discloses behavioral traits: live read from Xenarch with degradation to payments:null and paymentsError, full history across all payment links, non-owner restricted view, and the note field. It also clarifies the auth requirement and that reading is not charged. No annotation contradiction.

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 somewhat long and uses complex sentence structures, but every clause adds essential information about behavior, auth, and degradation. It is appropriately sized for the tool's complexity, though it could be slightly more concise.

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

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

Given no output schema and no annotations, the description is remarkably complete. It covers the full response structure, authority-based behavior, error degradation, historical scope, and cost implications, leaving little ambiguity for the agent.

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

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

The tool has zero parameters and the schema is empty, so the baseline is 4. The description adds meaning by explaining what the response contains, though there are no parameter details to elaborate on.

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 returns the org's entire billing picture, enumerating subscription status, spending caps, money, charge ledger, payments, and usage meter. It is specific and detailed, though it does not explicitly differentiate itself from sibling tools like usage_summary.

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

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

It provides clear context on when to use the tool, including owner authority requirements and the non-owner fallback to usage meter only. It also notes that reading billing is not charged. However, it does not explicitly mention alternatives or when not to use this tool.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It declares 'Read-only' at the end and describes the return shape and status values, giving the agent a good understanding of what to expect. It doesn't cover error handling or permissions, but for a read-only check this is sufficient.

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

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

The description is dense but efficient: it states the purpose, usage context, return structure, and read-only nature in a compact form. Every sentence contributes useful information without fluff.

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?

Without an output schema, the description fully documents the return value, including the `youHold`, `status`, and `heldBy` fields and their possible values. Combined with the usage guidance, it leaves no significant gaps for a tool of this simplicity.

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

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

The input schema already provides a 100% coverage with a description for the `identifier` parameter (example 'RTSC-49'). The tool description adds little beyond referring to the issue, so the schema bears the weight. 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 opens with a direct question 'Does THIS session hold an issue?' which clearly identifies the tool's purpose as checking session ownership. It distinguishes itself from sibling tools like claim_issue and release_issue by focusing on verification rather than modification.

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

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

The description explicitly states when to use it: 'before committing or opening a PR on a `rtsc-NN/` branch'. This provides clear context, though it does not explicitly list exclusions or alternative tools beyond positioning itself as a 'companion to the commit gate'.

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

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

With no annotations, the description carries the full burden. It discloses that checkpoints survive release/reclaim, renew the lease, and require the claim token. This covers key side effects and persistence, though overwrite behavior is not detailed.

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

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

Three sentences, front-loaded with the core purpose, then persistence, lease renewal, and auth requirement. Every sentence contributes, with no filler.

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

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

For a simple 3-param tool with no output schema or annotations, the description covers purpose, side effects, and auth. Minor gaps: no mention of return value or whether a new checkpoint replaces the old one, but the level of detail is adequate for an agent selecting the tool.

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

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

Schema coverage is only 33% (only 'note' has a description). The description adds meaning for 'claimToken' (requires the claim_token) and for 'note' (contents like done/next/gotchas/branch). However, 'identifier' is left vague, only implied by 'your claimed issue', and no format or examples are given.

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 records a handoff checkpoint on a claimed issue, listing specific contents (done, next, gotchas, branch/artifacts). This distinguishes it from sibling tools like check_claim or heartbeat.

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

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

It provides clear context: use this to persist progress across lease lapses or crashes, and it also renews the lease. It implies when to use it (before potential interruption) but does not explicitly name alternatives or exclusions.

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

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

With no annotations, the description carries the full burden. It discloses that claiming is a lease expiring in 30 minutes, that only heartbeat/checkpoint renew it, that a sweep returns the issue to todo, and that a worktree is mandatory. It also covers billing failure modes with tellHuman. This is exemplary 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 long but dense; every sentence adds operational value. It front-loads the primary purpose and key response fields, then delivers critical lease/worktree/billing guidance. While it could be trimmed, the length is justified by the tool's complexity and the severe consequences of misuse.

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 lacking an output schema, the description explains all return values: claim_token, branch, activeClaims, claimExpiresAt, and tellHuman for billing refusals. It covers failure modes, renewal semantics, and isolation requirements. Nothing critical is missing for an agent to use the tool safely and correctly.

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

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

The only parameter, `identifier`, is fully described in the schema ('e.g. XEN-12'), so coverage is 100%. The description adds only the phrase 'by id', which is trivial. The schema already documents the parameter; the description does not need to add more.

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 'Claim one specific issue by id' — a specific verb and resource — and explicitly contrasts it with 'next_issue' to prevent confusion. It names the input (identifier), failure conditions, and key outputs, making its scope 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?

States precisely when to use this tool: for claiming a specific issue by ID rather than having next_issue pick. It also specifies exclusions: fails if already held, not todo/doing, blocked, or non-work. The extensive worktree requirement gives concrete usage instructions, and the billing refusal section tells the agent how to react.

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

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

With no annotations, the description must carry the burden. It states it's a read operation, which is non-mutating, but does not disclose return format, error handling, or authentication needs. Minimal behavioral context beyond the verb.

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

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

The description is a single concise sentence with no unnecessary words or repetition. 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?

For a simple one-parameter read tool, the description is adequate but not fully complete. Without an output schema, it doesn't specify what 'read' returns (e.g., content, metadata), though the verb implies retrieval.

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 describes the parameter as 'Attachment id' with 100% coverage. The description reinforces 'by id' but does not add new meaning beyond what the schema provides, 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 'Read one attachment by id' uses a specific verb (read), names the resource (attachment), and indicates scope (by id). This clearly distinguishes it from siblings like list_attachments (plural) and save_attachment (write).

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

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

No explicit when-to-use or alternative guidance is provided. The phrase 'by id' implies it's for fetching a specific attachment, but it doesn't mention when not to use it or contrast with list_attachments.

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?

No annotations are provided, so the description carries the transparency burden. It discloses that blocking is computed and deadlines are derived, which adds behavioral context beyond a simple fetch. It does not mention error handling or side effects, but for a read operation this is acceptable.

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, information-dense sentence lists all returned facets without redundancy. 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 one simple parameter and no output schema, the description provides a thorough enumeration of return fields, including computed ones, making it sufficiently 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?

Schema coverage is 100% (identifier with example 'XEN-12'), so the schema already documents the parameter. The description does not add additional parameter meaning, hence the baseline score of 3.

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 resource ('one issue'), clearly distinguishing it from list_issues. It enumerates the exact scope of fields returned, so the tool's 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?

The phrase 'one issue in full' clearly implies usage for single-issue detailed retrieval, contrasting with list-oriented siblings. No explicit exclusions or alternatives are named, but the context is clear.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds useful context by stating the return includes an issue-status breakdown and that it defaults to the key's project. However, it does not discuss error behavior, auth requirements, or output format in detail, leaving some 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, focused sentence that front-loads the core action and integrates a key detail (issue breakdown) and default behavior. Every word earns its place with no redundancy.

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

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

For a simple getter with one optional parameter and no output schema, the description adequately conveys the purpose and the nature of the return value (project plus issue breakdown). It could be more explicit about the exact structure of the breakdown, but the essential information is present.

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

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

The input schema has 100% coverage for the single parameter 'prefix', with its own description 'Defaults to this key's project.' The main description repeats this same information, adding no new semantic detail. Thus, the parameter meaning is fully captured by the schema, making the description's contribution neutral.

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') with a clear resource ('a project') and adds a distinguishing detail: 'a breakdown of its issues by status.' This separates it from siblings like list_projects (which only lists projects) and get_issue (which focuses on a single 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 implies usage by explaining the default project behavior ('Defaults to the API key's project'), but it does not explicitly name alternatives or state when not to use this tool. There is no mention of list_projects for all projects or get_issue for a specific issue.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool extends an existing lease and returns the new expiry, which is useful, but it does not describe potential failure modes, side effects beyond the lease extension, or behavior when the token is invalid. More context would be valuable.

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

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

The description is concise, with three sentences that each add value: what it does, what it requires, and what it returns. No filler or repetition.

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

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

Given the low complexity and absence of an output schema, the description adequately covers the core behavior and return value. However, the unexplained 'identifier' parameter and lack of detail about the return format or error handling leave room for improvement.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'claim_token' but the actual schema property is 'claimToken', creating a potential mismatch. The 'identifier' parameter is not explained at all, leaving a significant gap for a tool with only two 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 tool's purpose: to extend a lease on a claimed issue during long-silent work. This specific verb+resource combination distinguishes it from sibling tools like claim_issue, release_issue, and check_claim.

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

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

It provides clear usage context ('during long-silent work') and notes the requirement of a claim token. However, it does not explicitly mention alternatives or when not to use this tool, so it falls just short of a 5.

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

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

With no annotations, the description carries the full burden. It discloses a notable behavior: obsolete attachments are flagged, not hidden. This goes beyond the basic 'list' action and gives insight into what the output will include. However, it does not mention return format or ordering, which for a simple read operation is acceptable.

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, focused sentence with no filler. It front-loads the verb and resource and adds a crucial behavioral note in parentheses. 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 1-parameter tool with no output schema, the description covers the essential purpose and a key behavioral nuance. It is complete enough for an agent to select and invoke correctly, though it could mention the return value or identifier format. Still, the simplicity of the tool reduces the need for more.

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 no description for the 'issue' parameter (0% coverage). The description clarifies that 'issue' refers to the parent entity of the attachments, but does not specify the expected format (e.g., ID, key). For a single parameter, this is adequate baseline; more detail would be better but not critical.

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

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

The description clearly states the verb 'List' and resource 'an issue's attachments', distinguishing it from sibling tools like get_attachment (retrieve single) and save_attachment (create/update). The parenthetical adds a specific scope detail, making 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 when to use the tool: when you need to see an issue's attachments. It provides clear context (attachments of an issue) but does not explicitly name alternatives or state when not to use it. For a simple list tool with obvious purpose, this is sufficient.

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

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

With no annotations, the description must carry the behavioral transparency burden. 'List' implies a read-only operation, and the chronological ordering is disclosed. However, it does not mention pagination, response format, whether comments are returned as full objects or references, or any potential limitations (e.g., archived comments). This is a moderate level of 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 key information. Every word contributes to the meaning, with no redundancy or filler. It is appropriately sized for a simple tool.

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 one-parameter list operation, the description is largely complete. It conveys the action, target, and ordering. While it omits details like pagination and return structure, the absence of an output schema and the straightforward nature of the tool reduce the need for extensive elaboration. It provides sufficient context for an agent to invoke the tool correctly in most cases.

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

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

The schema has a single required parameter 'issue' with no description (coverage 0%). The description clarifies that the parameter is the issue whose comments are listed, adding basic meaning beyond the raw schema. However, it does not specify whether the value should be an issue ID, key, or other identifier, leaving some ambiguity.

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

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

The description 'List an issue's comments in chronological (thread) order' uses a specific verb ('List'), identifies the resource ('an issue's comments'), and adds ordering context. It clearly distinguishes itself from siblings like list_issues (lists issues) and get_issue (retrieves a single issue), 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 intended usage is implied: to fetch comments for a particular issue. However, there is no explicit statement about when to use this tool versus alternatives (e.g., list_issues for issue lists or get_issue for issue details), nor any exclusions or prerequisites. The guidance is adequate but not explicit.

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

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

With no annotations provided, the description carries full burden. It clearly states that secrets/tokens are NEVER returned ('METADATA ONLY'), that the tool is read-only, and that the MCP surface excludes new repo connections. This provides critical safety and privacy information beyond basic list functionality.

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

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

The description is three sentences, front-loaded with the main purpose, and each sentence adds necessary information (row details, security caveat, creation limitation). It is slightly verbose for a simple list tool but remains efficient 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?

For a no-parameter tool with no output schema, the description is complete. It covers what the tool lists, the exact fields returned, the metadata-only nature, and the limitation that new connections are Dash-only. No missing critical information.

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

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

The tool has zero parameters, so the baseline is 4. The description adds value by specifying the output row fields (provider, repo, target project, hasToken, timestamps), which helps the agent understand the response even though there is no output 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 'List' with a clear resource ('the org's intake connectors') and provides the scope ('org's'). It also differentiates from sibling tools by noting the read + disconnect surface, which distinguishes it from creation or other connector operations.

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

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

The description explicitly states 'Connecting a NEW repo is Dash-only' and clarifies that this surface is read + disconnect, providing clear when-to-use guidance. However, it doesn't explicitly name the sibling tool for disconnect (revoke_connector), leaving a slight gap in alternative tool identification.

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

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

With no annotations provided, the description carries the full burden. It discloses default status filtering, ordering (priority-first, None last, recent tiebreak), and the derived slaState semantics. This is rich behavioral detail beyond a simple 'list' statement.

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

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

The description is compact and front-loaded, with four sentences each conveying valuable information: purpose, default behavior, filters, ordering, and SLA usage. 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 tool's complexity (7 optional params, no output schema), the description covers key behaviors: default filtering, ordering, SLA state, and a use case. It doesn't explicitly state the return array shape beyond compact fields, but that is sufficiently implied.

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 86%, so the schema already describes most parameters. The description adds tool-level behaviors (default filtering, ordering) but does not significantly add meaning to individual parameters 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 clearly states the tool lists issues in the project, with a specific compact format (author, createdAt, slaState). It distinguishes from siblings like get_issue and next_issue by emphasizing the list/filter/order behavior.

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

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

It provides clear usage context: defaults to active work, filters by multiple criteria, and explicitly recommends polling slaState:'breaching' for near-breach work. However, it does not explicitly mention alternatives or when-not-to-use, though the sibling list makes the purpose clear.

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

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

No annotations are provided, so the description carries the full burden. The verb 'List' implies a read-only operation, but the description adds no extra behavioral details such as sorting, pagination, or permissions. It is minimally sufficient for a simple read tool but lacks explicit safety confirmation.

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 immediately states the action, scope, and output content. There is 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?

With no output schema or annotations, the description should fully explain the return value. It tells the agent the list includes labels and issue counts but does not specify the exact fields, structure, or edge cases such as empty labels. Adequate for a simple list but could be more explicit about the response format.

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

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

The tool accepts zero parameters and the schema is empty, so the baseline is 4. The description reinforces the no-input nature by saying 'all labels' rather than indicating filterable options, adding clarity 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 ('List') and resource ('labels') with explicit scope ('in the org') and adds 'with issue counts' to define the output. This clearly distinguishes it from siblings like list_issues and save_label.

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 (when you need all org labels with counts) but does not explicitly state when not to use it or mention alternative tools. However, the scope is unambiguous, so the guidance is adequate.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals that both humans and agents are included and that they are the attribution targets for issues/comments. However, it omits details like pagination, ordering, whether inactive members are returned, or any side effects, which would be useful for a list operation.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and scope. 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 simple list tool with one optional parameter and no output schema, the description is largely complete. It defines the scope (org members) and clarifies the membership types. Minor gaps like return format or result ordering could be added, but given the simplicity, this is adequate.

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

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

Schema description coverage is 100%, with the 'query' parameter described as a partial name filter. The tool description restates this with 'Optionally filter by name' but adds no new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists members, specifying both humans and agents, and defines members as the 'users' issues and comments are attributed to. This distinguishes it from sibling tools like list_issues and list_labels.

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 one needs to see organization members, but provides no explicit guidance on when to use this tool over alternatives or any exclusions. It mentions optional filtering, but no when-to-use or when-not-to-use 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?

With no annotations provided, the description must carry the burden. 'List' implies a read-only operation, and the mention of fields adds some behavioral context, but it does not disclose auth requirements, order, pagination, or other traits. For a simple list, this is minimally adequate.

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

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

The description is a single, front-loaded sentence that efficiently states the action and relevant details. It contains no waste and is 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?

Lacking both an output schema and annotations, the description provides only the basic return fields. It omits details on pagination, ordering, or full response structure, but for a simple list tool this is close to adequate.

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

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

The input schema has zero parameters, so there is nothing to describe. The description adds the scope 'in the org' but doesn't need to explain parameters. The 0-parameter baseline of 4 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 'List projects in the org' clearly states the action (list) and resource (projects), and the parenthetical '(prefix, name, issue counter)' specifies the returned information. This distinguishes it from sibling tools like get_project and other list operations.

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 a list of projects is needed, but it does not explicitly mention alternatives or when not to use it. No contrast with get_project or other listing tools is provided, making the guidance limited to implied 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?

With no annotations provided, the description carries the full burden and does so excellently. It discloses that the key is returned only once, that there is no privilege change, and details the specific billing refusal behavior including the `tellHuman` field and the consequence that writes will keep failing.

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 long but every sentence earns its place, covering purpose, usage context, key lifecycle, and error handling. It is front-loaded with the main purpose and remains structured and readable.

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

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

Given the tool's low parameter count and absence of an output schema, the description is remarkably complete. It explains the return value ('raw key is returned ONCE'), error handling for billing refusals, and the operational context, leaving minimal ambiguity for the agent.

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

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

Schema coverage is 100% with a good description for the label parameter, so baseline is 3. The description adds meaning by explaining that the label distinguishes sessions ('distinctly labeled') and ties it to queue_status/whoami, which the schema alone doesn't convey.

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

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

The description clearly states the tool's function: mint a per-session API key bound to the agent's identity. It uses a specific verb ('Mint') and resource ('per-session API key'), and distinguishes itself by explaining how it makes concurrent sessions distinguishable in queue_status/whoami.

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 specifies when to use this tool ('The watchdog proxy calls this once at startup') and provides explicit exclusion behavior: do not absorb billing refusals, and do not continue as if the session were healthy. It also instructs the agent to relay `tellHuman` to a human, covering both usage and error handling.

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

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

With no annotations, the description takes full responsibility for behavioral disclosure. It covers atomic claiming, claim tokens, lease expiration, renewal via heartbeat/checkpoint only, billing refusal behavior, and the risk of shared checkouts—far beyond the minimal expectation.

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

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

The description is long but surprisingly tight: it front-loads the core semantics and then organizes operational guidance, prerequisites, failure modes, and lease rules into clear paragraphs. Every sentence contributes essential context for safe use of a high-stakes parallel dispatch tool.

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?

Without an output schema, the description explicitly enumerates return fields ({issues, ready, otherLanes, blocked, claimed}) and the tellHuman condition. It also covers worktree setup, dependency initialization, lease timing, and billing refusal, making the tool fully actionable in complex real-world scenarios.

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?

Although the schema already describes all three parameters, the description adds significant meaning: claim becomes a lease with a 30-minute expiry and worktree obligation, allLanes relates to otherLanes stranded-work counts, and n is contextualized as 'top N' in a priority-ordered wave. This is substantial added value.

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

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

The description opens with 'Wave dispatch for a fleet' and precisely defines the result: the top N eligible issues (todo + unclaimed + unblocked WORK), priority-ordered and parallel-safe. It clearly distinguishes itself from likely siblings like next_issue by framing itself as a batch, claimable dispatch operation.

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

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

It explicitly explains when to peek vs. claim, how allLanes affects scope, the mandatory worktree step after claiming, and the need to heartbeat before long stretches. It does not explicitly name next_issue as the single-issue alternative, but the usage context leaves little ambiguity.

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

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

With no annotations, the description fully discloses behavioral effects: status changes to 'doing', claim_token issuance, 30-minute lease expiry, renewal via heartbeat/checkpoint only, sweep re-queuing, billing refusal handling, and the requirement to use an isolated worktree. It also explains race conditions with other agents and why the worktree is mandatory.

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 very long, but the complexity of the tool justifies substantial detail. It is front-loaded with the primary purpose and then structured into logical sections: lane scoping, return values, lease semantics, worktree requirements, and billing failures. Some sentences are dense but earn their place; a bit of trimming could improve readability, so not a 5.

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?

Without an output schema, the description fully enumerates the response fields: issue, claim_token, ready, otherLanes, blocked, claimed, tellHuman, wave, branch, activeClaims, and claimExpiresAt. It also covers edge cases like empty queues, stranded work in other lanes, and billing refusals, leaving little ambiguity for the agent.

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

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

The sole parameter allLanes is already 100% described in the schema, so baseline is 3. The description adds meaningful context about lanes ('shared free pool', 'never another human's work', and the example of an absent owner), but the schema already captures the core default behavior. The extra examples push it above 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 opens with a specific verb and resource: 'Pull the next issue to work on, project-scoped' and explains the atomic claim behavior. It clearly distinguishes itself from siblings like next_batch (batch claiming) and queue_status (observing) by emphasizing that it actually claims and returns one 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 gives explicit when-to-use guidance for allLanes:true vs the default bare pull, and mentions next_batch as the alternative for batch claiming. It also provides post-claim operational instructions (worktree creation, heartbeat/checkpoint calls, lease expiration) that tell the agent exactly how to behave after invocation.

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?

Even without annotations, the description thoroughly discloses important behavioral traits: it is a soft delete, requires a reason, and includes a detailed billing failure mode with instructions to pass tellHuman to the user and not ignore write refusals. This goes far beyond generic mutation-tool descriptions.

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

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

The description is front-loaded with the main purpose ('Mark an attachment obsolete') and is well-structured overall. The extended billing guidance is verbose and includes repetitive all-caps emphasis, but each part provides actionable 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?

The description provides deep detail about the billing failure path but omits what a successful response returns and does not cover other error scenarios or side effects. Given no output schema and no annotations, this leaves gaps in the agent's understanding of the full execution flow.

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 describes only 'attachment' (id), leaving 'reason' with no description. The description merely restates that a reason is required without explaining what constitutes an acceptable reason or any format constraints, thus failing to compensate for the 50% schema coverage gap.

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

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

The description uses a specific verb and resource: 'Mark an attachment obsolete' and clarifies it is 'the delete-equivalent' that 'keeps it as a record,' clearly distinguishing it from other attachment-related tools like save/get/list_attachments.

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

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

The description clearly indicates this is the deletion operation for attachments, requires a reason, and provides context on when to act (billing refusal). It does not explicitly name alternatives, but the tool's role as the soft-delete for attachments is unambiguous given the sibling list.

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

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

With no annotations provided, the description fully discloses the two-step behavior, including the need for Bearer auth, server-side encryption at rest, optional filename/title URL parameters, and the output format of the POST. This greatly exceeds what the schema alone conveys.

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

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

The description is well-structured, starting with the core purpose, then the required follow-up action with a concrete curl example, and finally the alternative tool. Every sentence provides necessary information without 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?

Despite no output schema, the description explains the return values ({ uploadUrl } from prepare, and {id, url} from the POST) and gives an end-to-end example. It covers all aspects needed to use the tool correctly, including auth and the external upload step.

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 the sole parameter 'issue' already described with an example (RTSC-12). The description adds no additional parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the tool attaches a FILE (image/blob) to an issue over MCP, distinguishing it from save_attachment which handles plain links. It identifies the exact resource (issue) and action (prepare upload), making the purpose unmistakable.

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

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

It explicitly provides the workflow: returns uploadUrl, then POST raw bytes with Bearer header. It also names the alternative tool (save_attachment) for non-file links, giving clear when-to-use vs when-not-to-use 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It provides rich detail about what the tool returns (counts, SLA breaches, dependency-blocking, claims/lease expiry), which helps the agent know what to expect. However, it does not explicitly state that the tool is read-only or non-mutating, though 'diagnose' strongly implies 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, dense sentence that is front-loaded with the primary verb and resource ('Diagnose the queue'). It uses a clear list structure to enumerate output details, with no wasted words or filler. Every element 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 tool has no parameters, no annotations, and no output schema, the description must fully explain what the tool does and returns. It does this comprehensively by specifying exactly the diagnostic information provided (status counts, SLA pressure, dependency-blocked items, claims). This is sufficient for an agent to invoke and interpret the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameters and does not attempt to. It compensates by explaining what output the agent will receive, which adds overall utility.

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

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

The description clearly states the tool's purpose as 'Diagnose the queue' and enumerates specific outputs (counts by status, ready to pull, SLA pressure, dependency-blocked, claimed items). This specific verb+resource combination distinguishes it from siblings like next_batch/next_issue, which pull work, and check_claim, which checks a single claim.

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

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

The description gives clear context for when to use this tool: whenever you need a diagnostic overview of the queue. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5. The verb 'diagnose' implies usage for assessment rather than action.

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

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

With no annotations, the description carries the full burden. It discloses important behavioral limitations (rejection of AGENT, admin restrictions on reactivating owners/admins) and the effect of restoring org visibility + prior role. However, it doesn't specify error behavior for already-active members or missing IDs, leaving slight transparency 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 four sentences, each carrying essential information without redundancy. It front-loads the purpose, then systematically covers usage constraints, authorization, and input sourcing. No filler or repeated content from the schema.

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

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

For a simple one-parameter tool with no output schema and no annotations, the description covers purpose, constraints, and input origin thoroughly. It omits edge-case behaviors (e.g., reactivating an already-active member) but provides enough context for safe invocation in most scenarios.

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 memberId with 100% description, but the tool description adds value by specifying the source ('memberId from list_members/whoami') and clarifying it must be a suspended PERSON member id. This reinforces correct usage beyond the schema's static description.

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

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

The description clearly states the verb (Reactivate), the resource (suspended PERSON), and the effect (restores org visibility + prior role). It explicitly distinguishes from agents via 'Rejects an AGENT' and contrasts with retire_member, making the tool's scope unambiguous.

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

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

It provides explicit when-not-to-use guidance: 'Rejects an AGENT (retire is terminal — there's nothing to reactivate)'. It also includes authorization constraints ('an admin may reactivate ordinary members only, never a suspended owner or admin') and tells where to source the memberId ('memberId from list_members/whoami').

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

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

With no annotations, the description carries the burden of behavioral disclosure and does well: it mentions the mutation (reverts to todo), that comments/checkpoint persist, and that an optional note can be passed. However, it uses 'claim_token' while the schema defines 'claimToken', a minor inconsistency that could cause confusion.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds meaningful information. It is succinct and well-structured with 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?

Given the tool's simplicity and lack of output schema, the description covers purpose, side effects, persistence, and the optional handoff note. It does not explicitly describe the 'identifier' parameter or return behavior, but the core context is sufficiently complete for an LLM 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?

Only 33% of parameters are documented in the schema, so the description must compensate. It explains the 'note' parameter and implies the role of the claim token, but leaves 'identifier' entirely undocumented. The naming mismatch ('claim_token' vs 'claimToken') further weakens parameter clarity.

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 'give back' with the resource 'claimed issue' and the outcome 'reverts to todo', making the tool's function unambiguous. It also contrasts with the sibling 'claim_issue' by emphasizing the reversal action.

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 establishes clear context: use when you want to return a claimed issue, and it names a prerequisite (claim_token). It implicitly distinguishes from 'claim_issue' but does not explicitly state when not to use it or mention alternative tools like 'checkpoint'.

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

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

With no annotations provided, the description carries the full burden. It discloses a critical behavioral trait: how to handle billing refusals (replay tellHuman, do not continue read-only work, only an owner can fix it). This is significant and goes beyond what annotations would provide. However, it does not describe other behaviors like error handling for non-existent relations or success responses. Still, the billing disclosure is substantially transparent.

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

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

The description is front-loaded with the main purpose, then follows with a long but highly relevant billing warning. The warning is detailed and actionable, but it could be condensed. Overall, it is appropriately sized for the critical information it conveys, though slightly verbose.

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 removal tool with no output schema and no annotations, the description covers the core purpose and the most critical failure case (billing). It does not cover parameter semantics or other potential errors, but given the tool's simplicity, the coverage is adequate. The billing instructions are comprehensive enough to guide an agent.

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

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

The description does not explain any parameter beyond the schema. It only says 'same args as add_relation', which requires knowledge of another tool. With 0% schema coverage, the description fails to compensate. The parameter names (sourceId, targetId, type) are somewhat self-explanatory, but the description adds no semantic value.

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

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

The description clearly states the action: 'Remove a link between two issues'. It also references the sibling add_relation by saying 'same args as add_relation', which differentiates it as the inverse operation. This is a specific verb+resource combination, so purpose is very clear.

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

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

The description provides context for usage as the inverse of add_relation but does not explicitly state when to use it versus alternatives, nor does it mention any alternatives or exclusions. The billing refusal note gives guidance on handling that specific case, but not on general usage. So usage 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?

No annotations are present, so the description fully discloses that the operation is one-way (no reactivate), the conditional retention/hard-delete behavior, and the authorization model (human principal, agent carries principal's authority, admin restrictions).

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

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

The description is dense but every sentence adds critical operational or safety information, with the main action front-loaded. No filler.

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

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

For a terminal, irreversible action with nuanced auth and data-retention behavior, the description covers all key aspects: consequences, reversibility, alternatives, source of ID, and error conditions. No output schema is present, so no return-value explanation is needed.

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 covers 100% of the single parameter, but description adds context: memberId comes from list_members/whoami and cross-org members yield NOT_FOUND. This goes beyond the schema's minimal description.

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

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

The description opens with 'Retire an AGENT' and enumerates specific effects (revokes API keys, releases live claim, removes from roster). It explicitly contrasts with suspend_member for persons, distinguishing it from sibling tools.

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

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

States when to use: for agent offboarding; explicitly says for a PERSON use suspend_member instead and that retiring a human is rejected. Also provides memberId source and notes cross-org NOT_FOUND.

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

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

With no annotations, the description fully discloses key behaviors: the text remains as memory, the note is shown un-struck, and the refusal behavior is spelled out in detail (tellHuman relay, inability to self-fix, and the consequence of continuing). This goes far beyond a basic mutation description.

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

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

The description is three sentences, front-loaded with the core action. The lengthy billing-refusal sentence is dense but necessary for correct agent behavior, so it earns its place. Slightly wordy but not wasteful.

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 2-param mutation tool with no output schema and no annotations, the description covers the action, prerequisite, and a key failure mode. It does not describe successful response or other errors, but the provided information is sufficient for correct use. Small gap on success output.

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

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

The input schema already has 100% coverage with clear descriptions for both parameters (comment id source and note purpose). The description adds a requirement context but is mostly redundant. Baseline 3 for high schema coverage 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 clearly states the tool's action: 'Retract a comment (strike it through) instead of deleting — the text stays as memory.' This uses a specific verb and resource, and distinguishes the behavior from deletion. It also implies alternatives like save_comment or delete.

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

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

The description explicitly says 'instead of deleting', providing a clear alternative use case. It also states a prerequisite ('Requires a note explaining why it's no longer valid') and gives detailed failure-mode guidance for billing issues, including exactly what to do (pass tellHuman to the human) and what not to do (absorb the refusal).

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?

No annotations are provided, so the description carries full burden. It thoroughly discloses idempotency, org-scoping, NOT_FOUND for unknown/other-org ids, the 401 response, and the revoke-don't-delete behavior. This is exemplary 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 three sentences but packs every essential detail without fluff. It is front-loaded with the action, then explains behavior, side effects, and reconnect path. Every sentence earns its place.

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

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

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is remarkably complete. It covers what it does, side effects, scoping, error behavior, idempotency, and the path to undo, leaving no significant 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?

The schema already documents connectorId with 100% coverage, so baseline is 3. The description adds meaningful constraints beyond the schema: the connector must belong to YOUR org, and an unknown/other-org id results in NOT_FOUND, which clarifies valid parameter values.

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 ('Disconnect') and resource ('intake connector'), and clearly states the effect (revoked, webhook stops, 401). It distinguishes from sibling list_connectors by being a mutating action and references the source of the id.

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

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

It is clear when to use this tool (to disconnect an intake connector) and references list_connectors for obtaining the id. It also explains the alternative for reconnecting (use the Dash), though it does not explicitly contrast with non-existent sibling mutation tools 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?

With no annotations, the description carries the full burden. It discloses the billing refusal behavior (tellHuman) and instructs agents not to continue with read-only work, which is valuable. It does not describe normal success responses or other error modes.

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 main purpose is front-loaded in a short first sentence. The second sentence is long but necessary for the critical billing edge case. The description is appropriately sized.

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

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

For a simple tool with two required params and no output schema, the description covers the core action and a critical failure scenario. It omits the semantics of the optional 'title' parameter and success response details, but overall is complete enough for an agent to use.

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

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

Schema coverage is only 33% (only 'issue' described). The description clarifies that 'url' is a link/URL, but it does not explain the optional 'title' parameter. It partially compensates 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 opens with 'Attach a link (URL) to an issue,' which is a specific verb+resource statement. It differentiates from sibling tools like prepare_attachment_upload (file upload) and get_attachment (retrieve).

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 by stating the action, but it does not explicitly contrast against sibling tools or provide when-to-use/alternative guidance. The billing failure note is relevant to handling failures, not to selecting this tool over others.

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

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

With no annotations provided, the description carries the full transparency burden and rises to the challenge. It discloses the billing-related failure modes (BILLING_INACTIVE, MONTHLY_CAP_REACHED), the `tellHuman` response field, and instructs the agent to relay the message rather than absorb the refusal. This is genuinely useful behavioral context beyond a simple CRUD description.

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

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

The description is front-loaded with purpose, then justifies usage via shared memory, and closes with a critical failure-mode warning. It is longer than minimalist examples, but every sentence adds distinctive value; the billing warning is essential for correct agent behavior. It earns its length.

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

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

For a simple two-parameter write tool with no output schema, the description covers the core purpose, the shared-memory context, and a critical failure path requiring human intervention. It does not detail success responses or permissions, but those are largely inferable from the schema and sibling context. The failure-mode guidance is a strong addition.

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

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

Schema coverage is 50%: the `issue` parameter is well-described with an example, while `body` is only typed as string. The description's 'Add a comment' and 'record what you did and why' give broad semantic meaning to `body`, but it doesn't add specific formatting, length, or content guidance beyond what the name implies.

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 'Add a comment to an issue', which is a specific verb+resource combination that immediately distinguishes this from siblings like save_issue or retract_comment. The shared-memory rationale further clarifies the intent.

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 states that comments are shared memory and should record what you did and why, which implies when to use it. However, it does not explicitly contrast with alternatives (e.g., retract_comment for removal or save_issue for editing issue fields), leaving tool-selection guidance 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that create calls are rejected if dependency or work declarations are missing, that labels are replaced, that billing refusals require relaying tellHuman to a human, and that work:false issues are never claimed by agents. This goes well beyond a simple 'saves an issue' and exposes real operational traits.

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 long but every clause carries necessary information for a complex mutation tool. It is front-loaded with the primary purpose and then builds to edge cases like billing refusal. Slightly dense, and could benefit from bullet formatting for the create requirements, but remains efficient given the 12-parameter complexity.

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

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

Given the complexity (12 params, no annotations, no output schema), the description covers the core workflows, validation rules, and billing failure behavior thoroughly. The only notable gap is not describing the success return value (e.g., whether it returns the created/updated issue or just a status). Overall, it is complete enough for an agent to use the tool correctly, with minor ambiguity about the response shape.

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 12 parameters already have detailed descriptions in the schema, so the baseline is 3. The description adds cross-parameter semantics beyond the schema: it states the mandatory combination of blockedBy/noDependency and work on create, and that a create missing either is rejected. It also clarifies labels replacement and cancelReason's requirement, enriching the parameter model.

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

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

The description opens with 'Create an issue (omit `identifier`) or update one (pass `identifier`, e.g. XEN-12)', clearly stating the exact operation and the two modes. This distinguishes it from sibling read-only tools like get_issue and list_issues by identifying it as the create/update mutation 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 gives explicit conditions: 'Only `title` is required to create', 'CREATE requires TWO declarations', 'Setting status to `canceled` requires `cancelReason`', and detailed billing-failure handling ('do NOT absorb the refusal and continue with read-only work'). It tells the agent exactly when and how to invoke the tool, including rejection conditions for missing fields.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses two non-obvious behaviors: idempotency by name, and the specific billing failure handling (BILLING_INACTIVE/MONTHLY_CAP_REACHED) including the tellHuman relay instruction and the warning that read-only work is not a substitute. This goes far beyond a typical 'create/update' statement.

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

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

The description is front-loaded with a concise purpose statement, then a detailed warning about billing failures. The warning sentences are necessary and serve a clear purpose, though the passage is somewhat lengthy for a simple tool. No wasted words, but it could be tightened.

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 2-param tool with no output schema and no annotations, the description covers the core behavior (idempotent create/update), the key failure mode (billing), and the required agent action. It is reasonably complete, though it omits any hint about the success return value, which is not required by an output schema but could add clarity.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for 'name' by indicating it is the idempotency key, which is valuable. However, 'color' is not explained at all (e.g., expected format, optionality). The description partially compensates but leaves the color parameter under-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 'Create or update a label' with the specific resource 'label' and the verb 'Create or update'. It also adds the unique qualifier 'idempotent by name', which distinguishes it from sibling read tools like list_labels. This is a specific and differentiating 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 provides implicit usage context: creating/updating labels by name. It doesn't explicitly name alternatives (e.g., list_labels for reading), but it does give critical usage guidance about billing refusals: instructing the agent to pass tellHuman to a human and not continue with read-only work. This is clear context though not an explicit when-to-use vs alternatives statement.

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

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

With no annotations, the description fully discloses behavioral traits: hides the org, drops read/act gates, keeps the row for attribution, cascade-retires agents (terminal, keys revoked, strays deleted), and notes reversibility. It also documents refusal conditions and cross-org NOT_FOUND behavior.

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

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

Every sentence carries essential information—purpose, effects, reversibility, agent distinction, authorization, parameter source, and edge cases. The description is dense but well-structured, front-loading the core purpose and layering constraints logically.

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

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

Given no annotations and no output schema, the description covers all necessary context: operational effects, authorization requirements, alternatives, parameter sourcing, and failure modes. It is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema's memberId is already described as 'PERSON member id to suspend (from list_members)'. The description adds value by specifying the source as 'list_members/whoami' and reinforcing the type distinction (person vs agent), giving practical guidance 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 opens with a specific action verb and resource: 'Offboard a PERSON from the org (owner or admin)'. It distinguishes from sibling tools by explicitly pointing to retire_member for agents and reactivate_member for reversal.

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

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

Provides explicit when-to-use guidance: use retire_member for agents instead (suspending an agent is rejected), and reactivate_member for reversing the action. Also details authorization constraints (active owner/admin, admin limitations, refusal 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the meaning of the two money figures, warns that lifetimeMeteredEstimateUsd is a diagnostic not an amount owed, and clarifies what pendingUsd represents. It also states that reading is not charged, giving the agent confidence in calling 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 dense but efficient. It front-loads the core purpose ('Usage METER...'), then details return values and clarifies the key distinction between the two money figures. Every sentence earns its place, and the pointers to related tools are woven in naturally.

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

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

Given the absence of an output schema, the description successfully explains the return values, particularly the nuanced difference between the two dollar amounts. It also gives the agent a clear decision path to billing_summary for deeper billing context. No important information is missing for a zero-parameter tool.

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

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

The tool has zero parameters, so the schema is trivially complete. The baseline for 0 parameters is 4. The description does not need to explain parameters and instead spends its words on return value semantics, which is appropriate.

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

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

The description clearly states the tool's purpose: it's a usage meter for the org, returning activity volume metrics (reads, writes, ratio, rate card) and distinct money figures. It explicitly distinguishes itself from the sibling tool billing_summary by naming that tool as the one for the full billing picture.

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

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

The description provides clear usage guidance: it tells the agent when to use this tool (for usage activity) and explicitly directs to billing_summary for the full subscription/payment picture. It also notes that reading the meter is not charged, implying it's safe to call.

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

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

With no annotations, the description carries the full burden. It discloses the returned information (identity, org, project scope) but does not mention behavior on invalid or missing API keys, rate limits, or other error conditions. This is a minor gap for such a simple read-only tool, but the core behavior is transparent.

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

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

The description is a single sentence that is concise, front-loaded with the action ('Return'), and contains no fluff. Every word adds meaning.

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

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

This is a simple tool with no parameters and no output schema. The description fully explains what the tool returns, making it complete for the agent to understand the tool's purpose and behavior without needing additional context.

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

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

The schema has zero parameters, which sets a baseline of 4. The description appropriately adds no parameter-specific information since none exist. No additional clarification is needed.

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

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

The description uses a specific verb ('Return') and clearly states the resource: the calling identity, its org, and the project scope. This fully distinguishes it from sibling tools, which perform data manipulation or retrieval on other entities.

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 determine who is calling and what scope the API key has. It doesn't explicitly mention alternatives, but none exist among the siblings, so the guidance is sufficient for a unique introspection tool.

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