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

The description adds specific behavior (releasing reservations) beyond the annotations (readOnlyHint: false, idempotentHint: true), but it does not disclose side effects, error conditions, or what happens if the reservation does not exist or is already released.

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 redundancy. It is appropriately short for the simple action it describes, though it omits crucial details that would make it more useful.

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

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

The description lacks essential context such as when to use the tool, prerequisites, or behavioral nuances. Since there is no output schema, it also does not clarify expected outcomes, leaving the tool under-specified for practical 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?

The description does not explain any of the parameters (e.g., agent, patterns, lease_id). It gives no indication of how parameters affect the operation, leaving the schema to carry the full burden without any supplemental clarification.

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 (release) and the resource (file reservations) with a specific context (held by an agent). It is concise and distinct from sibling tools like file_reserve and file_renew.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, or any conditions that warrant its use. It only states what it does, not when to call 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 provided, the description carries the full burden of disclosing behavior. It mentions matching authority and revision but does not explain what happens on mismatch, success/failure side effects, idempotency, or concurrency behavior for this 12-parameter mutation. This is insufficient for a safe and correct invocation.

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

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

The description is a single, front-loaded sentence with no wasted words. It gets straight to the point and avoids redundancy or extraneous details, making it appropriately concise for a well-named 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?

Given the tool's complexity (12 required parameters, no output schema, no annotations), the description is severely under-specified. It lacks information about return values, error conditions, prerequisites (e.g., needing a lease from file_reserve), and its relationship to siblings like file_release. This leaves significant gaps for an agent to invoke it reliably.

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 by explaining parameter meanings. It vaguely references 'task-attempt authority and revision' which could relate to task_id, attempt_id, and expected_revision, but it does not map any of the 12 parameters to their purpose or how they interrelate. This leaves the schema's raw constraints alone, providing minimal 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 clearly states the action ('Renew'), the resource ('file lease'), and specific qualifiers ('active direct-v1', 'matching task-attempt authority and revision'). It succinctly distinguishes this from sibling tools like file_reserve and file_release by focusing on the renewal 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?

The description implies usage for renewing an existing lease but provides no explicit guidance on when to use this tool versus alternatives (e.g., when to renew vs. release) or prerequisites. The phrase 'with matching task-attempt authority and revision' hints at required conditions but does not elaborate on contexts 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds meaningful behavior: reservations expire after TTL and check_only toggles conflict-checking without creating reservations. It does not contradict annotations, and this context helps the agent understand lifecycle behavior.

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

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

The description is only three sentences, front-loads the core action, and each sentence adds distinct value: what it does, the check_only mode, and TTL expiry. There is no fluff or redundancy.

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

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

Despite having 16 parameters, no output schema, and complex coordination modes, the description omits important behavior such as conflict outcomes, return values, release/renewal expectations, and the difference between legacy and direct-v1 modes. It provides a useful overview but is incomplete for such a feature-rich tool.

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

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

Schema description coverage is only 44%, and the description does not compensate for the many undocumented parameters. It adds little beyond the schema for check_only and TTL, while leaving actor/agent modes, task_id, workspace_id, claim_token, coordination_mode, and other fields unexplained in prose.

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

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

The description uses a specific verb ('Reserve') with a clear resource ('files or glob patterns') and purpose ('prevent conflicts between agents'). This clearly differentiates the tool from sibling tools like file_release and file_renew by its core 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?

It provides some usage context by explaining the reservation's purpose and explicitly mentions check_only=true for conflict checks without reserving. However, it does not state when to prefer this tool over file_release or file_renew, nor does it mention prerequisites or follow-up actions.

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

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

Annotations indicate readOnly and idempotent, which the description does not contradict. The description does not add any additional side-effect information beyond what the annotations already convey, which is acceptable given the annotations are present. However, it could benefit from noting that negotiation is non-destructive.

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 gets straight to the point without any fluff or redundant phrasing. It efficiently communicates the tool's high-level 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?

The tool has a nested schema and an enum for requested_mode, indicating complexity. However, the description does not elaborate on the negotiation flow, expected return values, or how the parameters interact. Given the absence of an output schema, the description should provide more context about what the tool accomplishes and what information is exchanged, which it 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 input schema has no descriptions for any parameters (client, required, requested_mode). The tool description does not explain what these parameters represent or how they influence the negotiation. Since schema coverage is 0%, the description fails to compensate, leaving the agent without guidance on how to construct valid arguments.

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 negotiate ForgeSpec capabilities, covering coordination mode, schemas, features, and limits. This distinguishes it from sibling tools like tb_* or sdd_*, which likely serve different functions. However, it could be more explicit about the outcome or result of the negotiation process.

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

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

The description provides no information about when to use this tool versus alternatives. It does not mention any prerequisites, context, or scenarios where this tool is appropriate. The lack of usage guidance makes it difficult for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds value by listing the specific data categories returned (database integrity, system time, etc.), which enriches the agent's understanding of the tool's output beyond the annotations. It does not contradict annotations.

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

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

The description is a single, clear sentence listing all returned items without redundancy. It is front-loaded and contains no filler, making it highly efficient.

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

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

Given the tool's simplicity (no params, no output schema), the description adequately conveys the purpose and return content. It lists the main categories of data, which is sufficient for a health check. It could mention the output format, but that is not critical for this low-complexity 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 fully covered (100%). With no parameters to explain, the description need not add parameter details. The baseline of 4 for no-parameter tools 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 retrieves server health diagnostics, database integrity, system time, active leases, and version telemetry. The verb 'Get' plus the specific resource types make the purpose unambiguous and distinguish it from sibling tools like tb_status or tb_heartbeat, which address task/system liveness rather than full health diagnostics.

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

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

The description implies its use for health checks but does not explicitly state when to use it relative to alternatives. It lacks guidance on when not to use it or how it differs from similar status tools. The usage context is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safe read-only behavior is covered. The description adds that the tool 'returns full contract data', which is useful, but it does not disclose error behavior, not-found handling, or any authentication expectations. This is acceptable 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?

The description is concise and front-loaded. Each sentence adds value: the first defines the core action, and the second clarifies the expected return content. There is no unnecessary jargon or duplication.

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 low-complexity read tool with one parameter and read-only/idempotent annotations, the description is largely complete. It names the resource, the lookup method, and what is returned. It could be slightly more complete by explicitly describing not-found behavior or the meaning of SDD contract, but these are not critical for selecting or invoking 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?

The schema already documents the sole parameter fully: 'Contract ID to retrieve'. With 100% schema description coverage, the description adds little new parameter meaning beyond restating that lookup is by ID. It meets the baseline but does not exceed 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 operation: 'Get a single SDD contract by ID', with a specific verb, resource, and lookup key. It also distinguishes itself from sibling tools like sdd_list, sdd_save, and sdd_history by emphasizing single-contract retrieval.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, and no exclusions or conditions are mentioned. The phrase 'by ID' only implies the usage case; it does not tell the agent when to choose this over sdd_list or sdd_history.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds the chronological ordering detail, which is useful but minimal. It does not mention pagination, filtering behavior, or any edge cases, so it provides only mild context beyond structured data.

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

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

The description is two sentences with zero fluff. It front-loads the core action and provides a brief clarifying second sentence. No unnecessary words or redundancy.

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

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

With 7 parameters, no output schema, and no mention of pagination or filtering options beyond a vague 'for a project', the description is incomplete. It does not explain how to use cursor for pagination, the phase filter, or consistency mode, leaving the agent under-informed for effective invocation.

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

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

Schema description coverage is low (29%), with only project and limit having descriptions. The tool description adds no extra parameter information; it only mentions 'for a project'. With 7 parameters and several undocumented ones (phase, cursor, change_name, consistency, since_revision), the description fails to clarify their meaning or usage.

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

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

The description clearly states the tool's purpose: retrieving SDD phase history for a project, showing contract transitions in chronological order. This distinctly separates it from siblings like sdd_get or sdd_list, which would retrieve current state rather than history.

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

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

The description implies usage for a specific project and history retrieval, but does not explicitly state when to prefer this over other sdd_* tools or mention any exclusions. It provides context but lacks explicit alternatives or 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?

Annotations already declare readOnlyHint and idempotentHint, so the read-only nature is covered. The description adds the 'all contracts' scope and filter options, but does not disclose the pagination/limit behavior, which could be misleading given the default limit of 20.

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

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

The description is a single, tight sentence that front-loads the primary action and resource, then concisely mentions filters. Every word contributes value and there is no redundant 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?

For a simple listing tool with three optional parameters and full schema descriptions, the description covers the main purpose. However, it omits details about return format and pagination, especially given the 'all' claim versus the limit parameter, so it is not fully complete.

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

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

Schema description coverage is 100%, and the description only restates the 'project and phase' filters already present in the schema. It adds no additional meaning beyond the schema, 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 uses the specific verb 'List' with the resource 'SDD contracts' and clarifies scope ('all') plus optional filters. It clearly distinguishes from sibling tools like sdd_get by focusing on listing all contracts rather than retrieving a single one.

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 usage context: use this tool to list SDD contracts with optional project and phase filters. It does not explicitly state when not to use it or name alternative tools, but the intended use is obvious from 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?

Annotations already declare this is a write operation (readOnlyHint: false) and idempotent (idempotentHint: true). The description adds the context that it records a phase transition, which is useful, but it does not explain what the phase transition means, how validation failures are handled, or whether an existing contract is replaced. No contradiction with annotations.

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

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

Two short sentences, no redundant fluff, front-loaded with the core action ('validate and persist') and a secondary traceability detail. 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 write tool with 9 parameters and no output schema, this description is too shallow. It doesn't explain critical parameters like submitted_digest, expected_head_revision, or coordination_mode, nor what the response or side effects look like. The phase transition mention is vague without further context.

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

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

Schema description coverage is only 11%, with only the 'contract' parameter described. The description adds no meaning for the other 8 parameters (actor, api_version, schema_version, idempotency_key, submitted_digest, coordination_mode, parent_contract_id, expected_head_revision). It merely restates that an SDD contract is being saved, which is already evident from 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 validates and persists an SDD contract, and adds that it records the phase transition for project traceability. This distinguishes it from sibling tools like sdd_validate (validation only) and sdd_get/sdd_list (read 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?

No guidance is provided on when to use this tool versus alternatives such as sdd_validate for validation-only flows or sdd_get/sdd_list for reading contracts. The intended usage is implied but no explicit exclusions or alternatives are named.

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

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

Annotations provide readOnlyHint and idempotentHint, so the safe read-only nature is known. The description adds value by stating the output includes a confidence check and allowed transitions, which goes beyond structured annotations. It does not contradict annotations and adds helpful context about what the validation result contains.

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, two sentences with zero waste. It front-loads the action and purpose, then immediately states the return value. 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 one parameter, full schema coverage, and read-only annotations, the description is fairly complete. It mentions the output (validation result, confidence check, allowed transitions) which is useful. It could explain what 'phase schema' means, but that is likely domain-specific and understood from sibling tools. Overall, adequate for a simple validation 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 the single parameter 'contract' is described in the schema itself as 'JSON string of the SDD contract to validate'. The description does not add further meaning beyond the schema, so a baseline 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 action (validate), the resource (SDD contract), and the purpose (against the phase schema). It returns a validation result with confidence and transitions, which distinguishes it from sibling tools that handle boards, tasks, files, or other SDD 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?

There is no explicit guidance on when to use this tool versus alternatives like sdd_save or tb_status. The description implies validation before some phase transition but does not state prerequisites, alternatives, or exclusions. This is a clear gap.

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

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

No annotations are provided, so the description carries the full burden. It only reveals the basic add action and that the board should already exist; it does not disclose concurrency, idempotency, validation failures, permission requirements, or effects of missing board_id. 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 two short sentences with no filler. It is front-loaded and every sentence contributes useful information.

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

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

For a tool with 16 parameters, nested gates and capability objects, no output schema, and no annotations, this description is too sparse. It covers the core purpose but omits essential contextual details such as how gates work, idempotency methods, revision handling, and task creation rules beyond the 'should' note.

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 44%, and the text does little to compensate. 'Reference a spec and have acceptance criteria' gives some meaning to spec_ref and acceptance_criteria, but most parameters, including gates, capability, work_unit, expected_board_revision, and coordination_mode, are left without added meaning beyond their names.

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

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

Description clearly states the action ('Add a task') and target ('an existing board'), which is specific and unambiguous. It does not explicitly name sibling alternatives, but 'add' is enough to distinguish from update/claim/query tools.

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

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

The sentence 'Every task should reference a spec and have acceptance criteria' gives useful usage guidance about how tasks should be created. However, it does not explicitly describe when to use this tool versus alternatives, nor are exclusions or prerequisites beyond board existence 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 and does disclose meaningful behavior: the decision is 'immutable' and that 'asserted provenance is not authentication.' This is valuable caveat information, though it does not cover side effects like idempotency handling or potential failure 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 description is extremely concise: two sentences, no filler, with the core action front-loaded and an important caveat placed second. 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?

This is a complex tool with 13 parameters, nested objects, no output schema, and no annotations. The description only covers the high-level purpose and one limitation; it omits return behavior, error/retry semantics, expected_revision meaning, and other operational details. It is far from complete for an agent to invoke confidently.

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

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

Schema description coverage is 0% and the description adds only high-level conceptual mapping (e.g., 'approval decision' implies the decision field, 'task gate' maps to task_id/gate_id). Most required parameters such as expected_revision, idempotency_key, coordination_mode, api_version, and schema_version remain unexplained, so the description does not compensate for schema 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?

The description uses a specific verb ('Record') with a precise resource ('immutable direct-v1 approval decision with asserted provenance for a declared task gate'), clearly distinguishing this from sibling tools such as tb_grant or tb_handoff. It immediately identifies what action is performed and on what target.

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 recording approval decisions at task gates but provides no explicit when-to-use guidance, exclusions, or alternatives. It does not tell the agent when this tool should be chosen over similar siblings, leaving usage context only implicitly understood.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description reinforces this by using 'Query' and adds the behavioral nuance that this traces authority events historically. It doesn't mention pagination limits or data retention, but given the annotation coverage, the additional context (grant/revoke/approval decisions) is sufficient for an audit-log 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?

One short sentence, front-loaded with the verb and resource. Every word earns its place; no filler or redundancy.

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

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

For a simple read-only audit query with zero required parameters and full schema coverage, the description is complete. It doesn't need to explain return format since there's no output schema and the purpose is self-evident. Light on retention or ordering details, but these are reasonable omissions for this complexity level.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description adds no parameter-level detail beyond what the schema already documents for actor, event_type, board_id, and limit. No gap here, but also no enhancement.

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

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

The description clearly states a specific verb ('Query') and resource ('historical audit trail'), and specifies the event types covered ('authority grants, revocations, and approval decisions'). Though sibling tools also deal with authority events, this is the only audit-log tool, so it is distinguishable without needing to name alternatives.

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

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

The description implies this is for reading historical audit data, and the siblings tb_grant/tb_revoke/tb_approve make it natural to infer this is the read-side counterpart. However, it never explicitly says when to use this instead of querying live state, nor does it mention the alternative read tool tb_query. Contextual guidance is implicit, 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 the full burden. It implies a read-only 'query' operation and mentions 'bounded', but does not disclose potential side effects, authentication requirements, rate limiting, or the exact nature of the summaries. The phrase 'for recovery without messaging' hints at a non-messaging behavior but leaves many behavioral aspects unclear.

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 action and purpose. It avoids verbosity and is appropriately short, though it sacrifices some detail that might be expected for a complex 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?

Given 13 parameters, no output schema, and no annotations, the description is severely inadequate. It does not explain the meaning of key parameters, filtering options, pagination, or return format. For a tool of this complexity, the description needs to provide significantly more context to be useful.

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

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

Schema description coverage is 0%, and the description adds no meaning beyond the schema. It does not explain the purpose of required parameters like board_id and actor, nor optional ones like cursor, limit, status, etc. The one-sentence description provides no parameter context, failing to compensate for the lack of 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 a specific verb ('Query') and resource ('task status summaries'), and includes a distinct purpose ('for recovery without messaging'). This differentiates it from sibling tools like tb_status (single task) and tb_query, though it doesn't explicitly mention 'batch' or name alternatives.

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

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

The description provides a clear context ('recovery without messaging') but does not explicitly state when to use this tool over alternatives nor mention exclusions. It implies a specific use case but lacks guidance on when not to use it, such as for interactive queries or when messaging is required.

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 disclosure burden, but it only states a precondition. It fails to explain the side effects of claiming, lease semantics (lease_seconds), conflict behavior, idempotency guarantees, revision checks, or the need for subsequent heartbeats—all significant for a state-changing 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 two short sentences, front-loaded with the core action and followed by the key precondition. Every word earns its place; there is no repetition or filler.

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

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

For an 8-parameter, state-changing tool with no annotations and no output schema, this description is insufficient. It covers the initial eligibility rule but omits important invocation context such as lease handling, idempotency behavior, expected_revision semantics, and what happens after a successful claim.

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

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

Schema description coverage is only 25%, so the description needed to compensate, but it adds no parameter-level meaning. It does not clarify lease_seconds, idempotency_key, expected_revision, coordination_mode, or api_version, which are otherwise undocumented in the schema.

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

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

The description uses a specific verb ('Claim') and resource ('task for execution'), clearly distinguishing it from sibling tools like tb_add_task or tb_status. The additional precondition ('only tasks in ready status with all dependencies resolved') further sharpens 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 provides clear when-to-use guidance by restricting claims to tasks in 'ready' status with all dependencies resolved. It implies when-not-to-use but does not name alternatives such as tb_set_dependencies for unfinished dependencies or tb_heartbeat for maintaining an existing 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, the description must disclose behavioral traits. It only mentions atomicity for tasks, but omits potential side effects, idempotency behavior, required permissions, error handling, or rate limits. Critical behavioral aspects like the write nature (though implied by 'create') and the meaning of parameters like idempotency_key are not explained.

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, two sentences, with no redundant wording. It efficiently conveys the core purpose and the key optional behavior.

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

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

Given the tool has 9 parameters and nested structures, the description is too sparse. It does not explain the purpose of many parameters (e.g., idempotency_key, coordination_mode) or provide details on outputs or failure modes. The lack of output schema and behavior notes leaves gaps for a complete understanding.

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 some context for the 'tasks' parameter (inline creation), but does not elaborate on other parameters like name, api_version, idempotency_key, or coordination_mode. Since coverage is low, the description should compensate but does not.

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

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

The description clearly states the tool creates a new task board for a project, and explicitly mentions the optional inline creation of tasks. It distinguishes itself from the sibling tb_add_task by noting it avoids N separate calls.

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 create a board and optionally tasks in a single atomic call, contrasting with using tb_add_task separately. This provides clear guidance on 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?

Without annotations, the description carries the burden. It indicates events are 'authorized' and 'immutable', and ordering is 'stable revision order', but it does not explicitly state that the operation is read-only or any side effects, though 'query' implies a read.

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 with the verb 'Query', providing a clear core without unnecessary 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?

Given the complex schema with nested objects and many parameters, the description is too minimal to provide adequate context. It does not explain the purpose of the events, how parameters relate, or what the output will be, especially 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 description coverage is 0%, and the description does not explain any of the many parameters (e.g., board_id, actor, cursor, event_type). There is no indication of parameter usage or meaning, leaving users to guess.

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

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

The description clearly states the tool queries event deltas, indicating a retrieval operation. The mention of 'direct-v1' and 'stable revision order' adds specificity but may be cryptic for some users.

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 instead of others, nor any conditions or prerequisites. It does not differentiate from sibling tools that might also deal with events.

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 only states a read operation ('get full details') but omits behavioral traits such as error handling, authentication requirements, or if the task can be missing.

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 of 9 words with no redundant information. 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?

For a simple retrieval tool with one parameter and no output schema, the description is mostly complete but could be slightly improved by noting what happens if the task doesn't exist.

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 adds 'by ID' which is already implied by the schema parameter 'task_id'. With 100% schema coverage, the description adds no new semantic 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?

Description clearly states 'Get full details of a single task by ID.' with a specific verb (get) and resource (task by ID), distinguishing it from sibling tools like tb_add_task or tb_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 implies usage when full task details are needed, but provides no explicit exclusions or guidance on when not to use it 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?

Annotations already indicate a mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds valuable behavioral context beyond annotations by specifying that grants are 'attenuated' (restricted) and 'expiring' (time-limited), and that they require exact negotiation. This helps the agent understand the nature of the operation, though it does not disclose all side effects 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?

Two concise sentences deliver the core purpose and a key requirement without wasted words. The description is front-loaded with the primary action and is appropriately sized for the tool's complexity.

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

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

Given the tool's high complexity (8 required parameters, nested objects, no output schema), the description is insufficient. It lacks essential context about the negotiation protocol, the meaning of the capability object, the purpose of expectedBoardRevision, or what the return value looks like. Without an output schema, the description should fulfill this role, but it 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?

Schema description coverage is 0%, leaving the description to explain parameter meaning. However, the description provides no information about the eight required parameters, their roles, or how to construct them (e.g., capability, expectedBoardRevision, resource). The schema itself is self-descriptive with names but lacks contextual meaning, and the description does not compensate for the low coverage.

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

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

The description clearly states the action ('Create') and the specific resource ('task-authority grant') with distinguishing attributes ('attenuated, expiring'). It effectively differentiates from sibling tools like tb_approve or tb_handoff by focusing on grant creation with limited scope and duration.

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

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

The description implies usage for creating temporary, restricted grants and mentions a prerequisite ('Requires exact task-authority@1.0.0 negotiation'), but it does not explicitly state when to use this tool over alternatives. There is no direct comparison with sibling tools or clear exclusions, leaving the agent to infer 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 contradiction with annotations (readOnlyHint=false and idempotentHint=true align with 'Create'). The description adds meaningful context with 'reference-only attenuated' and the exact-negotiation requirement, which goes beyond what annotations convey. However, it does not disclose what the handoff actually does once created, what side effects occur, or what 'attenuated' concretely restricts.

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

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

Two short, front-loaded sentences with no filler or repetition. It is appropriately sized and the key qualifier ('reference-only attenuated') appears early. Minor deduction for under-specification of content relative to the tool's complexity, though the prose itself is lean.

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 high-complexity tool: 9 required params, deeply nested objects (capability, resource, refs), an exact API-version negotiation requirement, no output schema, and only minimal annotations. The description offers almost nothing to bridge these gaps — it never explains what 'negotiation' entails, how operations interact with capability, or what a successful handoff returns.

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

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

Schema description coverage is 0% and the description provides zero parameter-level information across 9 required parameters, including complex nested structures (resource, capability, refs). Since even high-end cases get a baseline 3 when the schema does the heavy lifting, and here the schema carries no descriptions, the description was obligated to compensate and entirely failed to.

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+resource ('Create a ... handoff') with qualifiers ('reference-only attenuated') that hint at the tool's distinct scope. However, it does not explicitly distinguish itself from semantically related siblings like tb_grant, tb_claim, or tb_approve, which also involve delegation-style 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 states a hard prerequisite ('Requires exact task-authority@1.0.0 negotiation') which conveys a precondition but gives no when-to-use guidance, no exclusions, and no mention of alternatives. An agent has little basis to choose this tool over tb_grant or tb_claim based on the text alone.

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

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

With no annotations, the description must disclose behavioral traits. It only states the action and mode, but does not mention what happens if the lease is not active, side effects of renewal, idempotency behavior, or error conditions. Key details like the effect of extend_seconds and expected_revision are absent.

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

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

The description is a single concise sentence that directly states the purpose. It is front-loaded and efficient, though it may be under-specified due to its brevity. It earns high marks for conciseness but not for completeness.

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 10 required parameters, no output schema, and no annotations, the description is highly inadequate. It does not explain any operational context, such as when to renew, what values to provide for parameters, or any expected response. The description provides almost no value beyond the tool name.

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

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

Schema description coverage is 0%, and the description provides no parameter explanations. It does not clarify the meaning of critical fields like expected_revision, claim_token, extend_seconds, or idempotency_key, leaving the agent to guess from names alone.

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

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

The description 'Renew an active direct-v1 task attempt lease' clearly specifies the action (renew), the resource (task attempt lease), and the mode (direct-v1). It distinguishes this tool from siblings like tb_claim (which creates leases) and tb_recover_claims (which handles failures).

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

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

The description implies the tool is used for renewing leases on active attempts, but it does not explicitly state when to use it versus alternatives, when not to use it, or any prerequisites. It lacks guidance on when a renewal is needed or how it relates to other lease operations.

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 convey behavior. It indicates a read-like operation ('list boards') and mentions the extra behavior with actor and direct-v1 context. It does not explicitly state side effects, but the phrasing suggests a non-mutating action, which is reasonably 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 two sentences and fairly concise. It avoids unnecessary fluff but includes a slightly verbose clause about 'direct-v1 context' and 'boards the actor owns or holds an active grant on.' Overall, it is well-structured and not overly lengthy.

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 explains the core behavior and a primary use case, but does not delve into edge cases or clarify the interaction between the separate version fields and the nested 'capability' object. Given the schema's complexity, additional context about parameter precedence or optionality 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 description explains the 'project' filter and mentions 'actor' in the context of the direct-v1 listing. It also references coordination_mode, api_version, and schema_version, covering most of the schema's parameters. However, the nested 'capability' object is not explicitly described, but its constituents are mentioned, providing adequate semantic coverage.

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

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

The description clearly states the action ('List task boards') and the optional filter by project, making the tool's primary function unambiguous. It also distinguishes the tool from others by mentioning the direct-v1 context and its purpose for discovering board IDs.

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 a specific use case: 'Use this to discover board IDs after context loss.' This implies when the tool is appropriate, though it does not explicitly contrast with alternatives like tb_get or tb_query, leaving some implicit 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 the full burden of behavioral disclosure. Words like 'stable, bounded, authorized' hint at consistency and access limits but are vague and unexplained. There is no information about pagination, error behavior, rate limits, or side effects. The tool likely performs a query, but the specifics of what 'snapshot' means or how 'bounded' applies are absent.

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

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

The description is a single short sentence, which is concise in length but not in substance. It front-loads a keyword 'Query' but then uses vague adjectives without explanation. It is not structured to convey key information first; it's simply too brief to be useful.

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

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

The tool has a complex schema (13 params including nested objects and enums) and no output schema. The description is grossly insufficient to understand what the tool does, its inputs, behavior, or return values. Given the lack of annotations, the description must carry full context but fails entirely. This is a major gap.

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

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

The schema describes 13 parameters, but the description provides zero insight into them. With 0% schema description coverageaine, the description does nothing to explain parameter meanings, relationships, or usage. For example, 'cursor' and 'status' are present in the schema but never mentioned. The description adds no value beyond the raw schema.

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

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

The description 'Query a stable, bounded, authorized direct-v1 task snapshot' is too vague. It identifies the verb 'query' and a resource 'task snapshot', but fails to clarify what a task snapshot is, what 'direct-v1' implies, or how this differs from sibling tools like tb_get or tb_batch_status. It doesn't even mention that it pertains to board tasks.

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. The description omits any context about supported use cases, prerequisites, or why one would choose tb_query over tb_get or other query-like siblings. No exclusions or differentiators 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 disclosure burden. It does reveal one meaningful behavior—recovered tasks are not automatically requeued—but it does not explain what happens to expired attempts, whether the operation is idempotent, or what failure modes exist.

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, front-loaded, and free of filler. Its brevity is effective, though it is compact at the expense of needed operational detail for such a complex 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?

The tool has 10 parameters, 7 required fields, nested objects, no annotations, and no output schema, yet the description is only two sentences. It fails to explain return values, prerequisites, side effects, or how the required parameters relate to the recovery operation.

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

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

Schema description coverage is 0%, and the description mentions none of the 10 parameters. It does not add meaning to fields like expected_board_revision, attempt_ids, limit, or the nested capability object, leaving the schema names to carry all semantic weight.

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 ('Recover') and a precise resource ('expired direct-v1 attempts'), making the tool's scope clear. It also distinguishes itself from nearby sibling tools like tb_requeue by stating that tasks require explicit requeue afterward.

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 'expired direct-v1 attempts' gives a clear target condition, and 'require explicit requeue afterward' implies this tool is not a substitute for requeue. However, it never explicitly names alternatives, states when not to use it, or explains the intended workflow relative to siblings like tb_requeue or tb_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 and no behavioral detail, the description offers zero transparency about side effects, authorization requirements, or failure modes. For a complex mutation tool, the agent is blind to what requeueing entails, making it highly risky to invoke.

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, technically concise, but it is under-specified. It lacks any elaboration on parameters, usage, or behaviors, which is not true conciseness but rather insufficiency.

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

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

Given the tool's complexity (10 parameters, nested objects, no output schema, no annotations), the description is drastically incomplete. It fails to explain the tool's workflow, required context, or expected results, making it impossible for an agent to use correctly without external knowledge.

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%, and the description mentions no parameters. The schema itself provides only types and constraints, so the agent cannot infer the meaning of task_id, expected_revision, idempotency_key, or the nested recover_active_dependents object. This is a critical gap.

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

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

The description states a specific verb ('explicitly requeue') and resource ('a recovered direct-v1 task'), which clearly indicates the tool's purpose. It distinguishes from siblings like tb_claim or tb_recover_claims by specifying the requeue action, though it could more explicitly contrast with alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives such as tb_recover_claims or tb_claim. The description gives no context on prerequisites, conditions, or exclusion scenarios, leaving the agent without decision-making support.

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

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

Annotations already communicate mutability, idempotency, and destructiveness, so the description adds meaningful context beyond those hints: it appends rather than replaces board ownership, and it requires exact task-authority negotiation. It does not detail all destructive consequences, but the annotations cover the core safety signal.

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

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

The description is two tightly worded sentences with no filler. The most important behavioral constraint ('without changing board ownership') is front-loaded, and the prerequisite is stated in the second sentence.

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

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

This is a 6-parameter mutation tool with nested capability schema and no output schema, so the description must carry substantial explanatory weight. It explains the operation's boundary and negotiation requirement but omits per-parameter meaning, expected success/error behavior, and visible effects for the caller.

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

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

Schema description coverage is 0%, and the description does not explain what each parameter means. It only hints at the capability negotiation concept, which maps loosely to 'capability', but actor, grantId, idempotencyKey, expectedBoardRevision, and reason are left entirely to the agent's interpretation of 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 is specific: 'Append an authority revocation' clearly names the verb and resource, and the qualifier 'without changing board ownership' disambiguates its scope from related tools like tb_grant or tb_handoff. This is a crisp, differentiating purpose statement.

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

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

The description gives a clear purpose and states an important precondition ('Requires exact task-authority@1.0.0 negotiation'), which helps an agent understand when the call is valid. However, it does not explicitly say when not to use it or name alternative tools for related operations, so usage guidance is primarily 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, the description carries the full behavioral burden. It does convey that the operation is atomic and replaces a dependency set, but it omits critical behavioral context such as optimistic concurrency via revision fields, conflict handling, permission requirements, and idempotency semantics.

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

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

One sentence, front-loaded with the key verb and noun, with zero filler. Every word contributes meaning.

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

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

This is a 10-parameter mutation tool with no output schema and no annotations. The description is too terse to provide adequate decision-making context: it does not mention revision checks, idempotency behavior, constraints on dependencies, or the expected outcome/receipt.

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%, and the description only maps conceptually to board_id, task_id, and dependency_task_ids. The remaining seven parameters—expected_board_revision, expected_task_revision, actor, idempotency_key, coordination_mode, api_version, and schema_version—are not explained or contextualized in the 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 states a specific verb ('replace'), a precise resource ('direct-v1 task's normalized same-board dependency set'), and an important qualifier ('atomically'). It clearly distinguishes this tool from generic sibling tools like tb_update or tb_query.

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

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

The description does not provide any explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusivity conditions. The atomic dependency-set replacement use case is only implied, with no when/when-not framing.

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 must fully disclose behavior. It states the tool is read-only ('Get'), but omits details like error handling (if board_id is invalid), response format (beyond 'grouped by status'), or any side effects. The description is too brief to cover necessary behavioral context.

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

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

The description is a single, clear sentence with no fluff. It could be slightly improved with structured formatting (e.g., listing output details), but it is 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?

Given the single parameter and no output schema, the description adequately conveys the purpose and output (status grouped by tasks). However, it does not specify the exact format of the status (e.g., JSON structure), leaving some ambiguity. Still, for a simple retrieval tool, this is reasonably complete.

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

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

The input schema already provides 100% description coverage for the single parameter 'board_id' with description 'Board ID'. The tool description does not add further meaning beyond implying it belongs to a 'task board'. Baseline score is 3 as per guidelines.

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

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

The description clearly states the action ('Get'), the resource ('current status of a task board'), and the output characteristic ('with all tasks grouped by status'). This is distinct from sibling tools like tb_get (likely board metadata) and tb_list_boards (list of boards).

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., tb_get, tb_unblocked). The description does not indicate prerequisites, exclusions, or preferred use 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, the description carries the full burden of behavioral disclosure. It states that it lists tasks with no unresolved dependencies, which is a behavioral filter. However, it does not mention whether the operation is read-only, what happens in case of no results, or any pagination/ordering behavior. The description is minimal but not misleading; it adds some context beyond the tool name.

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

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

The description is a single, clear sentence with no redundancy. It is concise and easy to parse, but given the complexity of the input schema (6 parameters, nested objects), the brevity might be considered under-specification. However, the description itself is efficiently written, achieving a balance of clarity without extra 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?

The description lacks essential context for a list operation. It does not specify the scope (e.g., tasks on a particular board, although board_id is required), what the output format is, whether pagination is supported, or any additional filtering options. The description gives only a high-level purpose without covering operational details, which is insufficient for a tool with multiple parameters and without annotations.

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 17% (only board_id has a minimal description). The tool description does not reference any parameters or explain how they influence the result. It does not mention the required board_id, nor any optional parameters like actor or capability. The description completely fails to help the agent understand the parameters or their interaction, leaving the agent to rely on the sparse 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 action ('List') and the resource ('all tasks that are ready to be worked on'), with a specific condition ('no unresolved dependencies'). This distinguishes it from sibling tools like tb_status or tb_query, which serve different purposes. The verb and scope are precise and unambiguous.

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

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

The description provides clear usage context: it is used to find tasks that are ready for work. While it does not explicitly mention when not to use it or compare to alternatives, the description implicitly indicates when this tool is appropriate (when you need a list of actionable tasks). No exclusions are stated, but the context is enough for an agent to infer suitable 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 provided, the description carries the full burden of behavioral disclosure. It does reveal two useful behaviors: the done-status transition constraint and that notes are stored as timestamped entries. But it does not mention side effects like claim requirements, idempotency, revision checks, or what the response returns, leaving significant behavioral aspects undisclosed.

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

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

The description is two sentences, starts with the core action, and contains no filler. Every clause adds value: the main purpose, the status-change caveat, and the note-storage behavior.

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

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

The tool has 13 parameters, nested objects, no output schema, and no annotations. The description only covers the core update action and one transition rule, leaving many important aspects (auth/claims, idempotency, revision handling, evidence links, return values) unaddressed. It is not complete enough for an agent to safely invoke this tool in all contexts.

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 (23%), so the description must compensate. It adds semantics for status updates and note appending, but 10 of 13 parameters remain unexplained in both the schema and the description (actor, claim_token, expected_revision, idempotency_key, evidence_links, capability, etc.). This is insufficient for a parameter-heavy tool.

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

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

The description clearly states the action ('Update a task's status and/or append notes') with a specific resource (task) and function. It distinguishes itself from sibling tools like tb_add_task or tb_claim by focusing on updating existing tasks rather than creating or claiming them.

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

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

The description provides clear context for when to use the tool: update status or append notes. It also gives an important usage rule: moving to 'done' requires current status 'in_progress' or 'in_review'. However, it does not explicitly mention alternatives or when-not-to-use conditions, so it stops short of full guideline coverage.

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