retasc

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

Given no annotations, the description carries the full burden. It discloses that blocks/blocked_by form a dependency graph and that cycles are rejected. However, it does not specify if duplicate relations are allowed, what happens on success, or error conditions (e.g., missing issue IDs). More behavioral details would improve 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 extremely concise with only two sentences, front-loading the action and types, and adding a key behavioral note. No unnecessary words; every sentence earns its place.

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

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

For a simple linking tool with no annotations, output schema, or nested objects, the description covers types and a behavioral constraint (cycle rejection). It lacks details on return values or error handling but is mostly complete for its scope. Minor gaps prevent a perfect score.

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

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

With 0% schema description coverage, the description must compensate. It lists the 'type' enum values but does not explicitly define 'sourceId' and 'targetId' as issue IDs, relying on context. This is minimal semantic addition; a brief clarification would help.

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), specifies the possible types (blocks, blocked_by, related, duplicate), and distinguishes from sibling tool 'remove_relation' by focusing on creation. It provides enough detail to understand the tool's primary function.

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

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

The description implies usage for linking issues, but lacks explicit guidance on when to use this tool versus other issue-related tools (e.g., save_issue). No context is given for when NOT to use it or alternatives like remove_relation for removal.

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 burden and excels: it discloses access restrictions (owner vs non-owner), data source (Xenarch), failure mode (degradation to null + error if unreachable), and side-effect statement ('not charged'). All behavioral traits are 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 core purpose and provides comprehensive details, but it is somewhat dense and uses all caps for emphasis. While no unnecessary words, it could be slightly more streamlined. Still above average.

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, the description fully explains the return values: subscription status, spending caps, money items, charge ledger, confirmed payments, usage meter. It also covers access conditions and error handling, making it complete for an agent to understand what to expect.

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?

There are no parameters, so the baseline is 4. The description adds value by explaining what the tool returns without needing parameter details, but since no parameters exist, the score is naturally high.

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 retrieves the org's entire billing picture, listing specific data elements (subscription status, spending caps, money breakdown, charge ledger, payments, usage meter). It uses a direct verb (implied 'get') and resource ('billing picture'), and the sibling tools are unrelated, so differentiation is not needed.

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 the tool (to get the full billing picture) and provides critical usage context: owner authority required for full data, non-owners get only usage meter with a note, and that reading billing is not charged. It effectively guides the agent on appropriate 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?

Without annotations, the description carries the full burden. It declares read-only behavior, lists return fields (youHold, status, heldBy), and explains possible status values. This covers the main behavioral traits, though it lacks detail on error handling or identifier validation.

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 two sentences, front-loading the key question. The second sentence is slightly dense but packs necessary detail. 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 simple tool (one parameter, no output schema), the description adequately explains the return structure and purpose. Minor gaps exist (e.g., missing error handling), but overall sufficient for correct invocation.

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

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

Schema coverage is 100% (parameter 'identifier' described as 'e.g. RTSC-49'). The description adds context about the format (rtsc-NN) but does not significantly extend the schema definition. 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's purpose with a specific verb ('does...hold') and resource ('issue'). It positions itself as a session-aware companion to the commit gate, distinguishing it from sibling tools like 'claim_issue' or 'release_issue' by emphasizing verification before commit/PR.

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 advises when to use the tool: 'before committing or opening a PR on a rtsc-NN/ branch'. It implies when not to use by contrasting with the commit gate, but does not provide explicit exclusions or alternatives beyond the 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?

No annotations provided; description reveals key behaviors: 'SURVIVES release + reclaim', 'renews your lease', and persistence across runtimes. Does not mention idempotency or limits, but sufficiently transparent for a simple checkpoint 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?

Two well-structured sentences front-loading the core purpose. Every word earns its place with zero fluff. Efficient and focused.

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

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

No output schema, but tool is simple. Description covers key side effects (lease renewal, persistence) and usage scenario. Lacks return value hint, but overall adequate for its complexity.

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

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

Only 'note' has schema description; description adds format detail ('Markdown: done so far / next steps / gotchas / branch'). 'identifier' and 'claimToken' lack explanation beyond 'Requires the claim_token', leaving coverage gaps.

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

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

Clearly states the verb 'Record a handoff checkpoint' and the resource 'on your claimed issue', with specific content details. It distinguishes from siblings like 'heartbeat' by combining checkpoint recording with lease renewal.

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 context for use: 'when your lease lapses or you crash' and 'resumes from here instead of restarting' implies when to call. Mentions prerequisite 'Requires the claim_token' but lacks explicit disclaimers against alternatives.

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

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

With no annotations, the description carries full burden. It discloses failure conditions, return values (claim_token, branch, activeClaims), and critical behavioral context about worktree isolation. It does not explicitly state if claiming is reversible or detail all state changes, but provides substantial behavioral insight.

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

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

The description is fairly long but well-structured, starting with core purpose, then failure conditions, response details, and workflow instructions. Each part serves a purpose, though the worktree instructions are detailed. Slightly verbose but justified for safety.

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

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

The tool is complex with conditions, a custom response, and a mandatory follow-up action. The description covers all aspects: eligibility conditions, response fields (claim_token, branch, activeClaims), and the critical worktree workflow. Without an output schema, it fully explains return values and necessary steps.

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

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

The schema covers 100% of the single parameter 'identifier' with a description ('e.g. XEN-12'). The tool description does not add additional parameter meaning beyond restating 'by id'. Baseline score of 3 is appropriate given high schema coverage.

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

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

The description clearly states 'Claim one specific issue by id (instead of letting next_issue pick)', specifying the verb (claim), resource (issue), and distinguishing it from the sibling tool 'next_issue'. It also enumerates failure conditions, fully clarifying the tool's 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 explicitly tells when to use this tool (to claim a specific issue by id) and when not to (if already held, not in todo/doing, blocked, or non-work). It provides a mandatory workflow instruction about using git worktree and explains when it can be skipped, offering clear guidance on usage and alternatives.

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

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

The description implies a read-only, non-destructive operation, which is clear. However, no annotations are provided, and the description does not disclose behavior on missing IDs, return format, or error handling.

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 is front-loaded and easy to parse. It could potentially add minor context without losing conciseness.

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

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

For a simple get-by-id operation with one parameter and no output schema, the description is mostly adequate. Missing return format is acceptable given typical conventions, but a note on not-found behavior would improve completeness.

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

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

The parameter 'attachment' is fully described in the input schema as 'Attachment id.' The description adds no further detail beyond the schema, achieving baseline given 100% schema coverage.

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

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

The description clearly states the verb 'Read' and the resource 'attachment', specifying the identifier 'by id'. This distinguishes it from sibling tools like list_attachments and save_attachment.

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

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

No guidance is provided on when to use this tool versus alternatives like list_attachments or obsolete_attachment. The description does not mention exclusions or context for selection.

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 carries the full burden. It describes the return payload but omits behavioral traits such as read-only nature, authentication needs, rate limits, or side effects.

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?

Single sentence with front-loaded verb and clear enumeration of returned fields; no wasted words, though could benefit from slight restructuring for readability.

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 and lack of annotations/output schema, the description covers the return fields well but lacks behavioral context such as whether the request is mutable or requires special permissions.

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 one parameter. The description adds context about the response but not about the parameter itself beyond what the schema provides (e.g., example identifier format).

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 retrieves a single issue with comprehensive details (body, status, priority, etc.), distinguishing it from siblings like list_issues (which lists) or save_issue (which modifies).

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

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

The description implies usage for fetching a single issue but does not specify when to use it versus alternatives like list_issues or next_issue, nor provide exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a breakdown by status and defaults to the API key's project. It does not mention side effects, auth requirements, or error conditions.

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

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

The description is a single, front-loaded sentence with no extraneous information. Every word serves a purpose.

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 single parameter and no output schema, the description provides essential behavior and default. It lacks details on the format of the 'breakdown of issues by status,' which would help an agent understand the response.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the default behavior of the 'prefix' parameter, which goes beyond the schema's 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 tool retrieves a project and a breakdown of its issues by status. The verb 'get' and resource 'project' are specific, distinguishing it from siblings like list_projects (listing all) and get_issue (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 mentions it defaults to the API key's project, implying when to omit the prefix. However, it provides no explicit guidance on when to use this versus siblings like list_projects or get_issue, nor any 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?

No annotations provided; description discloses that it requires a claim_token, returns new expiry, and implies mutation (extending lease). Lacks details on failure modes or side effects.

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?

Single concise sentence with key info, 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?

Covers purpose, requirement, and return, but missing explanation for the identifier parameter, which is required. Adequate for a simple tool but incomplete.

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

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

Schema coverage is 0%; description explains claim_token but not the identifier parameter, leaving one required parameter undocumented.

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

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

The description clearly states the action (extend lease) and resource (claimed issue), distinguishing it from siblings like claim_issue (claiming) and release_issue (releasing).

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 context 'during long-silent work' but does not explicitly mention when not to use or compare with alternatives like check_claim.

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 bears full responsibility for behavioral disclosure. It only mentions that obsolete attachments are flagged, not hidden. It does not disclose pagination, order, permissions, or format of results.

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 concise (one line) and front-loaded with the main purpose. However, it sacrifices necessary detail for brevity.

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

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

Given the lack of output schema and annotations, the description is insufficient. It doesn't clarify return format, pagination, or whether file content is included. The schema coverage is 0%, so the description should compensate but does not.

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 0% coverage and the description does not elaborate on the 'issue' parameter beyond implying it is an identifier. No format, restrictions, 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 verb 'list' and the resource 'issue's attachments'. It also distinguishes itself from siblings by noting that obsolete attachments are flagged, not hidden, which aligns with sibling tool 'obsolete_attachment'.

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

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

No guidance is provided on when to use this tool versus alternatives like 'get_attachment' or 'obsolete_attachment'. There is no mention of prerequisites or context where this tool is appropriate.

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 adds the ordering behavior (chronological) but lacks disclosure about pagination, response format, or error handling for invalid issues.

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?

Single sentence front-loading the verb and resource, with no extraneous information. Every word earns its place.

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

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

For a simple read tool with one parameter and no output schema, the description fails to mention what is returned (list of comment objects) or any pagination behavior. It is adequate for basic understanding but incomplete.

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

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

The sole parameter 'issue' is not described in the schema (0% coverage). The description only implies it's an issue identifier but does not clarify format (e.g., ID, key) or provide constraints.

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

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

The description explicitly states the action 'List' and the resource 'issue's comments', and adds the ordering information 'chronological (thread) order'. This distinguishes it from sibling tools like save_comment or get_issue.

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

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

The description implies usage by requiring an issue identifier, but does not explicitly state when to use this tool versus alternatives like save_comment or retract_comment. No exclusions or context about filtering are provided.

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

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

With no annotations, the description fully discloses behavioral traits: read-only, metadata-only, secrets never returned, and the limitations of the tool.

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

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

Three sentences that are all informative, though slightly longer than minimal; still front-loaded with the main action.

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

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

No output schema exists, but the description covers the return fields and key constraints (no secrets, Dash-only for new connections), making it complete for this 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?

No parameters exist, but the description adds value by detailing the output structure (provider, repo, target project, hasToken, timestamps) beyond the empty 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 clearly states it lists the org's intake connectors with examples (GitHub Issues → Retasc issues), and the output fields, 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?

Explicitly states it's read-only and that connecting a new repo is Dash-only, providing clear guidance on when not to use and contrasting with other tools.

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

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

Given no annotations, the description discloses key behaviors: hides done/canceled by default, ordering priority-first, and slaState derivation. It does not mention pagination beyond limit, but the schema addresses that.

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

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

Two sentences packed with information, front-loaded with the main purpose. Could be slightly more structured, but no wasteful content.

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

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

Covers return shape, filtering, ordering, and SLA state usage. Lacks pagination details beyond limit, but acceptable for a list tool with no output schema.

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

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

Schema coverage is high (86%), but description adds value by explaining default behavior and slaState derivation. It provides context beyond parameter descriptions, such as hiding done/canceled and the meaning of slaState 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 clearly states it lists issues in the project with author, createdAt, and derived slaState. It distinguishes from sibling tools by specifying compact format and filtering, though not explicitly contrasting with get_issue or next_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?

It explains default active work filtering, available filters, ordering, and provides a specific use case for polling slaState:'breaching'. However, it does not explicitly mention when not to use this tool or alternatives.

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

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

No annotations are present, so the description must carry the full burden of behavioral disclosure. It only states it's a list operation, implying read-only behavior, but does not mention pagination, rate limits, authentication requirements, or any side effects.

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 of seven words, efficiently conveying the core functionality without waste. Every word earns its place.

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

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

Given the zero parameters and lack of output schema, the description is minimally adequate. It tells what the tool does but omits details about pagination, return format, or whether the list is exhaustive. It could be improved with such 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 with 100% schema description coverage. Since there are no parameters, the description need not add parameter meaning. The 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 clearly states the tool lists all labels in the org with issue counts. The verb 'list' and resource 'labels' are specific, and the scope 'in the org' is explicit. It distinguishes from sibling tools 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, limitations, or scenarios where another tool might be more appropriate.

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 burden. It discloses the resource type (members) and the filtering option, but does not mention pagination, authentication requirements, or any side effects. Basic behavioral info is present but missing deeper context.

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

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

The description is extremely concise with one sentence that front-loads the purpose and includes a key detail about attribution. 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?

Given the simple tool with one optional parameter and no output schema, the description is mostly complete. It explains what members are and the filter. Minor gap: could mention pagination or return format, but for a list tool this is acceptable.

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% for the single parameter 'query', and the description adds that it filters by member name (partial). This adds marginal meaning beyond the schema, so 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 (humans and agents) in the org, and explains that these are the users issues and comments are attributed to. This specific verb+resource combination distinguishes it from sibling tools like list_issues or list_comments.

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 it lists members and optionally filters by name, but it does not provide guidance on when to use this tool vs alternatives, nor does it 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 only states that it lists projects but does not disclose whether it is read-only, any side effects, or behavior like pagination or ordering.

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 extremely concise, using a single sentence to convey purpose and output format. Every word is necessary.

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 parameterless list tool, the description is fairly complete, stating what is returned. However, it omits details like whether all projects are listed or if there is an implicit scope.

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?

There are no parameters, so the baseline is 4. The description adds value by specifying the output fields (prefix, name, issue counter) beyond the empty 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 clearly states the tool lists projects in the org and specifies the fields returned (prefix, name, issue counter). This distinguishes it from sibling list 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, 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?

No annotations present, so description carries full burden. Discloses no privilege change, one-time return of raw key, and binding to user identity. Could mention idempotency or multiple-call 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?

Three concise sentences: purpose, usage context, and behavioral notes. No redundant words; front-loaded with key 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?

Tool is simple with one optional param and no output schema. Description explains return behavior and access implications adequately. Could add note about error states or when not to call.

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

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

Schema already describes the label parameter with 100% coverage. Description adds value by providing an example (host#pid) and clarifying auto-derivation when omitted.

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?

Clearly states it mints a per-session API key tied to the user's identity and label. Differentiates from siblings like whoami or queue_status by focusing on session key creation.

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?

Mentions that the watchdog proxy calls it at startup, implying typical use case. Does not explicitly exclude other uses or list alternatives, but context 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 discloses key behaviors: mutual independence of issues, default peek, claim mode with claim_token, lane-scoping, and return structure. Missing details on failure modes or edge cases, but adequate for safe use.

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

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

Two dense sentences covering core functionality and modes. Could be better structured (e.g., bullet points for return fields), but no extraneous content.

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

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

Given three parameters and no output schema, the description provides enough to understand input, behavior, and output shape. Lacks error handling details but suitable 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 has 100% coverage for all three parameters. Description adds context beyond schema, including defaults (n=5, claim=false, allLanes=false) and semantic meanings (e.g., claim_token, lane scope). Adds value beyond 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 clearly states the tool returns top N eligible issues for wave dispatch, specifying inclusions (todo, unclaimed, unblocked WORK) and exclusions (work:false containers), with effective-priority ordering. It distinguishes itself from siblings like next_issue by focusing on batch dispatch.

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?

Explains peek mode for planning and claim mode for atomic claiming, and lane-scoping vs allLanes. However, it does not explicitly state when not to use this tool or provide alternative tools for different scenarios.

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

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

With no annotations provided, the description fully discloses behavioral traits: atomic claim, status change to 'doing', inclusion of advisory wave list, branch info, and activeClaims count. It also warns about shared checkout risks and mandates worktree usage.

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 thorough but verbose, containing operational instructions and warnings that extend beyond the core behavior. While well-structured and front-loaded, the length is excessive for a single-boolean-parameter tool, earning a middle score.

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 of the tool (claim tokens, batch advice, lane scoping, worktree requirements) and the absence of an output schema, the description is remarkably complete. It explains all relevant response fields and required post-claim steps.

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 covers 100% of the single parameter (allLanes) with a description. The tool description adds rich context about its effect (reaching into other humans' lanes) and default behavior, providing value beyond the schema. A baseline of 3 is appropriate, but the added explanation justifies a 4.

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 that the tool pulls the next issue to work on, atomically claims the highest-priority unblocked todo, and returns it with a claim_token. It distinguishes from siblings like next_batch and claim_issue by specifying batch claiming and lane scoping.

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 specifies when to use the tool (to claim next work), when not (non-work issues, others' lanes by default), and provides alternatives like allLanes:true or next_batch. It also explains the behavior when no issue is eligible and advises on worktree isolation.

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 burden. It states the action (soft delete) and requirement (reason), but does not detail consequences (e.g., availability, permissions, reversibility).

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 effectively communicates the core purpose and requirement without extraneous information.

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

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

Given no annotations and no output schema, the description provides key behavioral context (soft delete, record keeping, reason requirement). Could be more complete on effects, but adequate for an experienced agent.

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

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

Schema description coverage is 50% (only 'attachment' has description). The description adds that a reason is required, which is already in schema as required. It adds marginal value beyond the schema.

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

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

The description clearly states the verb 'Mark obsolete', the resource 'attachment', and clarifies it's the delete-equivalent that keeps a record. It distinguishes from sibling tools like 'save_attachment' and 'get_attachment'.

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 (soft-delete an attachment) but does not explicitly list when not to use or alternatives. However, the purpose is clear enough given the sibling 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?

No annotations exist, so the description must carry the full burden. It describes outputs in detail but does not disclose whether the operation is read-only, any authentication requirements, or potential side effects. The term 'diagnose' suggests read-only, but it's not explicit.

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

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

A single sentence that is front-loaded with the primary action ('Diagnose the queue') and efficiently lists all key output components without unnecessary 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 no output schema, the description explains the key return values (counts, SLA, dependency-blocked, claimed). It lacks structural details (e.g., format of deadlines or lease expiry) but is sufficient for a diagnostic 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 input schema has zero parameters, so the description does not need to explain parameter semantics. Baseline 4 applies as the description adds no redundant parameter information.

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

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

The description uses a specific verb 'Diagnose' and clearly identifies the resource 'queue'. It enumerates distinct outputs (counts by status, SLA pressure, dependency-blocked, claimed) differentiating it from siblings like next_issue or claim_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 use for diagnostic purposes but does not explicitly state when to use this tool versus alternatives like next_batch or check_claim. No exclusions or prerequisites are mentioned.

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

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

With no annotations provided, the description carries the full burden. It discloses the action is owner-gated and rejects AGENT members. However, it does not mention behavior when reactivating an already active member or error handling, slightly reducing 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?

Two sentences, no redundant words, perfectly sized. Every sentence adds value: the first states the main operation and effects, the second clarifies constraints and parameter source.

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 param, no output schema), the description covers all necessary context: action, authorization, parameter source, and limitations. Nothing is missing.

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

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

Schema coverage is 100% (1 param described). The description adds context beyond the schema by specifying 'PERSON member id' and the source (list_members/whoami), which aids 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 specifies the action ('Reactivate a suspended PERSON'), the scope ('owner-only'), and the effects ('restores org visibility + their prior role'). It distinguishes from sibling tools like suspend_member and retire_member by noting that AGENT reactivation is rejected.

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

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

Explicitly states when to use: 'owner-only', and when not to use: 'Rejects an AGENT (retire is terminal — there's nothing to reactivate)'. Also provides the source for memberId ('from list_members/whoami'), guiding correct 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?

With no annotations, the description covers key behavioral traits: reverting to todo, persistence of comments/checkpoint, and the purpose of the note parameter. It lacks details on error cases or idempotency but is fairly comprehensive.

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, front-loaded with the core action and requirements. Every sentence serves a purpose without unnecessary detail.

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

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

Given the absence of output schema, the description adequately explains the effect (revert to todo) and what persists. It does not describe the return value or error scenarios, but the operation's outcome is clear.

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 low (33%). The description adds value for the note parameter ('Optional final handoff checkpoint') but provides little extra for identifier and claimToken beyond stating the requirement. It partially compensates for missing schema descriptions.

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

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

The description clearly states the action: 'Give a claimed issue back to the queue (reverts to todo).' It specifies the resource (issue) and the state change, distinguishing it from sibling tools like claim_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 mentions the prerequisite ('Requires the claim_token') and explains the persistence of comments/checkpoint. It also guides when to use the optional note parameter. However, it does not explicitly state when not to use this tool or provide alternatives.

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

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

With no annotations, the description carries the full burden. It only states that the tool removes a relation, without disclosing behavioral traits like idempotency, error handling, permissions, or side effects. This is insufficient for a mutation tool.

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

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

The description is a single concise sentence with no extraneous words. It is well-structured and easy to read, though it could benefit from additional detail without becoming 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?

Despite the tool having three required parameters and no output schema or annotations, the description provides no information on return values, error states, or prerequisites. It is under-specified for reliable autonomous 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 0%, so the description must compensate. It briefly notes 'same args as add_relation', which provides minimal context but does not explain individual parameters. The enum for type is self-explanatory, but sourceId and targetId remain ambiguous.

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

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

The description clearly states the verb 'Remove' and the resource 'link between two issues', and references 'add_relation' which clarifies its role as an inverse operation. It effectively conveys the tool's 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?

No explicit guidance is provided on when to use this tool versus alternatives, such as 'add_relation' or other sibling tools. The only hint is the note about same args as add_relation, but that does not help in choosing between tools.

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

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

Discloses irreversible nature, revocation of keys, conditional deletion (hidden vs hard-delete), and auth requirements. With no annotations, description fully covers behavioral 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?

Dense but well-structured: main action first, then details, alternatives, and parameter source. 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?

With no output schema, description explains consequences and error cases. Adequately covers all needed context for a single-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?

Schema coverage is 100% and description adds context: memberId is for AGENT from list_members/whoami, and wrong org yields NOT_FOUND. Adds value beyond 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 clearly states the verb 'Retire' and the resource 'AGENT', and distinguishes it from sibling tools like suspend_member. It specifies the terminal offboard action and lists effects.

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

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

Explicitly tells when to use (for AGENT) and when not (for PERSON use suspend_member). Specifies owner-only access and source of 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 full burden. It discloses that the comment is struck through but text remains, and the note is shown un-struck. No mention of permissions, side effects, or failure modes, but adequate for a simple 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?

Two concise sentences, front-loading the core action and adding the note requirement. No wasted words, efficient and clear.

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?

Does not describe return values or error cases, but given the tool's simplicity and no output schema, it is fairly complete. Could mention success indicators but not critical.

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 both parameters well-described. The description adds no new meaning beyond the schema, so it meets the baseline but does not improve it.

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: retract a comment by striking it through, distinguishing it from deletion by preserving the text. It also mentions the required note, making the tool's purpose specific and distinct from siblings.

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

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

The description implies when to use retract instead of delete (when text should stay as memory) and requires a note. It differentiates from deletion but does not explicitly mention when not to use or alternatives like editing.

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 covers behavioral traits: the effect (stops webhook syncing, 401 response), idempotency, org-scope, error behavior for unknown/other-org id (NOT_FOUND), and clarification that it is not a deletion. No contradictions with annotations (none present).

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

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

The description is extremely concise, using three short sentences to convey all necessary information. It is front-loaded with the action and resource, and every sentence adds value 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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is complete. It covers purpose, effect, idempotency, scope, error case, and follow-up action. No gaps remain.

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 'connectorId' is described in the schema as 'Connector id from list_connectors.' The description adds context that the id comes from list_connectors and clarifies that unknown or other-org ids result in NOT_FOUND. This goes beyond the schema description, providing source and error handling information.

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

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

The description clearly states the action (disconnect/revoke) and the resource (intake connector), specifying that it marks it revoked and stops the webhook with a 401 response. It distinguishes from deletion by stating 'revoke-don't-delete' and provides context on org-scoping and error 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?

The description clearly says when to use the tool (to disconnect a connector by id from list_connectors) and what it does not do (delete, just revoke). It mentions idempotency and org-scoping. However, it does not explicitly state when not to use it or compare to alternatives among siblings, but no direct alternative exists.

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 provided, so description fully responsible. It indicates a creation action but does not disclose effects like overwriting, validation, permissions, or idempotency. For example, it does not state whether attaching a duplicate URL is allowed or if title is optional.

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?

Extremely concise (one sentence) but lacks necessary substance. The brevity compromises informativeness; it is an under-specification rather than elegant conciseness.

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

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

No output schema and limited schema coverage. Description fails to explain return values, error conditions, or side effects. For a tool with 3 parameters and no annotations, the description is insufficient for an agent to understand behavior.

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

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

Schema description coverage is only 33% (only 'issue' described). Description does not clarify the purpose of 'url' and 'title' parameters beyond the basic definition. It adds no value over the schema's sparse descriptions.

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

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

Description clearly states the tool attaches a URL link to an issue, with verb 'attach' and resource 'link (URL)'. It distinctively differs from sibling tools like 'get_attachment' (retrieve) and 'obsolete_attachment' (deprecate). However, it could be more specific about the action being a save/create.

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

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

No guidance on when to use this tool versus alternatives such as 'add_relation' or 'save_comment'. Lacks any context about prerequisites, conditions, 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?

No annotations are provided, so the description carries the full burden. It accurately states the create behavior but does not disclose any side effects (e.g., notifications), auth requirements, or idempotency. It is adequate but not rich.

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

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

Two sentences, each earning its place: the first states the purpose, the second adds contextual motivation. Efficient and front-loaded.

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

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

No output schema and no annotations, but the tool is simple. The description is somewhat complete for a basic create operation, but it omits return values and error scenarios, leaving gaps.

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

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

Schema description coverage is 50% (only 'issue' has a description). The description adds no parameter information beyond 'Add a comment' and 'body' is not described. Thus, it does not compensate for the missing schema coverage, scoring 2.

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 'Add a comment to an issue', which is a specific verb+resource. It also adds context about comments being shared memory, but does not explicitly differentiate from sibling tools like 'retract_comment' or 'list_comments', hence a 4.

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

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

The description says 'record what you did and why', implying a logging use case. However, it lacks explicit when-to-use or when-not-to-use guidance and does not mention alternatives, providing only implied usage.

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 covers important behaviors: create requires two declarations, work semantics, status transitions (especially review flow), and that work:false issues are never claimed. Minor omissions (e.g., atomicity, failure handling) but still strong 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 well-structured, starting with the core rule and then detailing requirements. Some parts are slightly verbose (e.g., work explanation), but every sentence adds necessary context for correct usage.

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 12 parameters, create/update duality, and conditional requirements, the description covers all necessary aspects: create-only mandatory fields, update via identifier, status-specific rules, and work semantics. No critical gaps.

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

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

Schema coverage is 100%, but the description adds substantial meaning: groups create/update logic, explains the interdependent relationship between blockedBy and noDependency, details work's decision criteria, and clarifies status effects. This goes far beyond schema descriptions.

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

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

Description clearly states 'Create an issue (omit identifier) or update one (pass identifier)'. It distinguishes the two modes with the identifier parameter and explains the action, making it distinct from sibling read-only or claim 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?

Provides explicit rules for create vs. update, and details requirements like the two declarations for create, but does not explicitly state when to use alternatives (e.g., get_issue for reads). However, the context is clear enough for an agent to infer usage boundaries.

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

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

The description discloses idempotency by name, which is a key behavioral trait. However, without annotations, it fails to mention other aspects like whether the tool is destructive, requires permissions, or has rate limits. The idempotency note provides moderate 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 sentence with no wasted words. It is front-loaded with the action and resource, and includes an important qualifier (idempotency) in a concise parenthetical.

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

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

For a simple tool with two parameters and no output schema, the description is adequate but incomplete. It lacks return value information and does not specify behavior for missing or optional parameters. With no annotations, more context would be beneficial.

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 add meaning. It does not explain the 'name' or 'color' parameters beyond the schema fields. The agent must infer their roles from context, which is insufficient for accurate invocation.

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

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

The description clearly states 'Create or update a label' with a specific verb and resource, and adds 'idempotent by name' which further clarifies behavior. It distinguishes from sibling tools like list_labels and save_comment by focusing on 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?

No guidance is provided on when to use this tool versus alternatives like list_labels or save_attachment. The description does not mention prerequisites, context, or 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?

No annotations provided, so description carries full burden. Discloses all behavioral aspects: hides org, drops gates, keeps row, terminal cascade for agents, reversibility via reactivate_member, and owner-gating.

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?

Description is detailed but not overly verbose; each sentence adds essential information. Could be slightly more concise, but front-loads the key action.

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 single parameter, no output schema, and no annotations, the description covers all necessary context: purpose, authorization, parameter source, side effects, error handling, and distinction from siblings.

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 already describes memberId well (100% coverage), but description adds value by mentioning whoami as an additional source, earning a 4.

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?

Clearly states it offboards a PERSON from the org, hides the org, drops from gates, keeps row, and cascades-retires agents. Distinguishes from sibling tools: 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?

Explicitly states when to use for person vs agent, notes owner-only gate, provides error conditions (self, last owner, other org), and source of 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 details what is returned (reads, writes, ratio, rate card, two money figures) and explains the meaning of the money figures. It states reading is not charged. Does not cover latency or rate limits, but overall 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?

Description is a single paragraph but well-structured: starts with purpose, then enumerates outputs, clarifies key terms, and ends with guidance. Concise despite length; each sentence 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 zero parameters and no output schema, the description fully explains what the tool returns and how to interpret the money figures. It also provides sibling tool guidance, making it complete for the tool's 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?

No parameters exist; schema coverage is 100% trivially. The description does not need to add parameter info. It appropriately focuses on output semantics.

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

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

Clearly states it is a usage meter for the org, distinguishing it from a bill. Explicitly mentions it returns reads, writes, ratio, rate card, and two distinct money figures. Differentiates from sibling billing_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?

Provides explicit guidance: 'For the full picture... use billing_summary.' Also notes that reading the meter is not charged, indicating when it is safe to use.

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

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

With no annotations, the description must fully disclose behavioral traits. It states it returns data but doesn't explicitly confirm it's read-only, safe, or free of side effects. It also omits authorization or rate limit details, though these are likely minimal.

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

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

The description is a single, well-structured sentence that front-loads the key action and results. No unnecessary 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 has no parameters and no output schema, the description sufficiently explains what it returns (identity, org, project) and its purpose. No 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?

There are no parameters (100% schema coverage). With zero parameters, the baseline is 4, and the description does not need to add parameter meaning 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 clearly states the tool returns the calling identity, its org, and the scoped project. The verb 'Return' and the specific resources make the purpose unambiguous, and it distinguishes from sibling tools which deal with issues, attachments, etc.

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 needing identity info, but lacks explicit guidance on when not to use it or alternatives. However, given the simplicity, the purpose is self-evident.

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