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

Annotations declare destructiveHint: true, but description describes only an append operation, which is typically non-destructive. Fails to disclose any destructive behavior or side effects, contradicting the annotation.

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

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

Two sentences, front-loaded with purpose, no redundant information. 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?

Description covers usage scenario but omits details about the 'role' parameter and any behavioral traits beyond the annotation contradiction. No output schema, so more completeness would be beneficial.

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

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

Schema coverage is low (33%), with only the 'message' parameter having a description. The tool description does not add any information about 'sessionId' or 'role' parameters, failing to compensate for the coverage gap.

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

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

Description clearly states action (append), resource (feedback session), and context (after thumbs up/down). Distinguishes from sibling tools like open_feedback_session or finalize_feedback_session.

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

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

Provides a clear scenario: 'Call this when the user types additional context after giving thumbs up/down.' Does not explicitly list when not to use or alternatives, but the scenario is specific enough.

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?

Description mentions 'time-limited' which adds some behavioral context beyond the destructiveHint annotation. However, it does not disclose that approvals may be revocable or that the tool itself creates a record.

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 is concise and front-loaded with the verb 'Grant'. However, it could be structured to highlight key parameters or usage.

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

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

No output schema and description does not explain return values or side effects. With 5 parameters and 2 required, more context on behavior or results 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?

Schema coverage is 100% with descriptions for all parameters. The description adds no additional meaning beyond what is already in the input 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 the verb 'Grant' and resource 'time-limited approval for edits or publish actions that touch protected files'. It distinguishes from sibling tools by focusing on approval of protected file actions.

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. Implies usage when needing to approve protected file actions, but lacks exclusion criteria or comparative 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 mark the tool as destructive (destructiveHint: true), so the agent knows it's a mutating operation. The description adds useful context about how vague feedback is handled (logged and returned with a clarification prompt instead of memory promotion). However, the specific destructive impact or side effects are not disclosed, so it stops short of full transparency.

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

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

The description is two short sentences with no filler. The first sentence states the core action, the second adds an important conditional behavior. Every word earns its place.

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

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

With 14 parameters, nested objects, enum constraints, and no output schema, the tool is complex. The description only addresses the minimal use case and gives no guidance on provenance (memorySource), failure-type classification, rubric scores, or return behavior. This leaves significant gaps for correct invocation.

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

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

Schema description coverage is only 43%, leaving many parameters (e.g., tags, whatWorked, guardrails, rubricScores) without explanations. The tool description only clarifies the core signal/context pair (up/down and one-line why) but does not compensate for the large undocumented parameter set, making it difficult for the agent to correctly populate optional fields.

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 captures an up/down signal plus a one-line reason, and mentions the specific behavior for vague feedback (logged and returned with a clarification prompt). This specific verb+resource+behavior distinguishes it from sibling feedback tools like feedback_summary or open_feedback_session.

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

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

The description implies usage when you have up/down feedback to capture, but it does not explicitly state when not to use this tool or mention alternative feedback pathways (e.g., open_feedback_session or reflect_on_feedback). No exclusions or alternatives are provided, so guidance is only implied.

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

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

Annotations already indicate readOnlyHint: true, so the description's 'Evaluate' aligns. It adds context about checking safety for multiple operations, but does not elaborate on behavioral traits (e.g., what checks are performed, what happens if state is unsafe). With annotations present, the description adds modest value.

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

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

The description is a single sentence that front-loads the core purpose, with no unnecessary words. It is concise and well-structured.

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

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

Given 5 optional parameters, no output schema, and annotations providing readOnlyHint, the description covers the tool's overall purpose. However, it does not detail what 'operational integrity' entails or the return format, but the schema and annotations fill some gaps. Overall, it is sufficiently complete for a safe read-only check 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 100%, so each parameter is documented. The tool description does not add extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'Evaluate' and clearly identifies the resource as 'current repo state' with explicit scope for PR, merge, release, and publish operations. This distinguishes it from sibling tools that focus on specific actions (e.g., get_branch_governance, approve_protected_action).

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

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

The description implies usage before PR, merge, release, and publish operations, but lacks explicit when-to-use or when-not-to-use guidance compared to the large set of sibling tools. No alternatives 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?

The annotation declares destructiveHint=true, which signals this is a write operation. The description adds meaningful behavioral context: the operation is append-only, does NOT authorize spending, and creates an independent human-escalation request. This goes beyond what the annotation provides by clarifying the non-authorization semantics, which is critical for safe use. However, it doesn't disclose what happens on duplicate entries, whether the human escalation is blocking, or what the cryptographic binding implications are beyond what the schema's toolName/toolInput descriptions mention. With a destructiveHint present but description adding semantic nuance, score 3 is appropriate.

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

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

Two sentences with zero waste. The first sentence states the core function, and the second overrides a dangerous potential misconception ('does not authorize spending'). Every word earns its place. It could add a bit more about when to use it, but for the length it has, it's 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?

This is a complex tool (10 params, 8 required, nested objects, cryptographic binding semantics) with no output schema and low schema description coverage. The description is too brief to fully equip an agent for correct invocation. It explains the overall purpose and a critical safety caveat, but doesn't explain the requisition lifecycle relationship (how reserve/settle interact), what the expected outcome is (no output schema), or the evidence structure. Given the complexity, a bit more detail is warranted, though the critical safety distinction is present.

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

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

Schema description coverage is only 30% (3 of 10 params have descriptions: toolName, toolInput, sourceMessageId), which is below the 50% threshold, so the description must compensate. The description itself adds no parameter-level detail, leaving the meaning of amountUsd, vendor, purpose, evidence, taskId, ttlMs, and idempotencyKey entirely to the schema's type definitions. The schema describes the crypto-binding semantics for toolName and toolInput already, so those params are covered. The description could have explained the evidence array's role in supporting the escalation, but the gaps in parameter semantics remain unaddressed.

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+resource ('create an append-only purchase requisition and independent human-escalation request') and clarifies the scope ('does not authorize spending'). It distinguishes from sibling tools like settle_purchase_requisition and request_human_escalation, though it doesn't explicitly name them as alternatives. The key differentiator—that this is append-only and does not authorize spending—is valuable given the many related purchase requisition tools.

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

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

The description notes the tool is append-only and escalates to humans but does not explain when to use this vs. siblings like reserve_purchase_requisition, settle_purchase_requisition, or request_human_escalation. Given the large cluster of related purchase tools, explicit guidance on when to choose this one would be highly valuable. The no-authorization clarification helps but doesn't cover the decision boundary between this and the other requisition lifecycle tools.

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

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

Annotations already declare readOnlyHint=true. The description adds that it uses 'past feedback', implying a reliance on historical data, but does not disclose other behavioral traits like performance constraints or data volume sensitivity.

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

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

A single sentence of 12 words conveys the essential purpose. It is front-loaded with the verb and object, with no superfluous 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 simple, read-only tool with one parameter and no output schema, the description is largely sufficient. It does not explain the output format, but the domain likely expects uncertainty values. Slight gap, but overall complete given the minimal context.

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

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

The input schema covers 100% of parameters with a clear description ('Tags to analyze for uncertainty'). The tool description reiterates this meaning but adds no further semantics (e.g., tag format, constraints, or cardinality). Baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('estimate') and resource ('uncertainty for a set of tags'), and adds domain detail ('Bayesian', 'based on past feedback'). This clearly distinguishes it from sibling tools like 'feedback_stats' or 'describe_semantic_entity'.

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 explicit conditions, prerequisites, or exclusions are mentioned, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, so the description's 'Get' aligns with that. However, no additional behavioral details (e.g., data sources, filtering, rate limits) are provided. With annotations covering the safety profile, the description adds minimal extra 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, concise sentence that immediately conveys the tool's purpose. Every word earns its place with no redundancy.

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

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

Given no parameters, no output schema, and a straightforward read operation, the description is mostly complete. However, it could clarify what 'stats and recommendations' entail or how they are generated, but this is a minor 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?

There are zero parameters, and the schema coverage is 100% (vacuously). The description does not add parameter information, but none is needed. Baseline score of 4 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 'Get feedback stats and recommendations' clearly states the function: retrieving statistics and recommendations related to feedback. It uses a specific verb and resource, distinguishing it from sibling tools like 'feedback_summary' or 'capture_feedback', though the exact scope is ambiguous.

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 (e.g., feedback_summary, reflect_on_feedback). There are no when-to-use or when-not-to-use hints, leaving the agent without context for selection.

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

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

Annotations already indicate readOnlyHint=true, and the description aligns with 'Get summary'. However, it fails to disclose any behavioral traits beyond what annotations specify, such as what constitutes 'recent' or the nature of the summary.

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

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

The description is a single sentence with no fluff, but it is too sparse for a tool with no output schema and only one undocumented parameter. Conciseness is achieved at the expense of necessary detail.

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

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

Given no output schema and only one ambiguous parameter, the description provides insufficient information for an agent to correctly invoke the tool and interpret results. The term 'summary' is undefined, and 'recent' is not quantified.

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 single parameter 'recent' (type number) has no description in the schema or the tool description, leaving its meaning (e.g., days, hours, count) completely ambiguous. With 0% schema coverage, the description should clarify 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 it retrieves a summary of recent feedback, but the term 'feedback' is vague and does not differentiate from sibling tools like feedback_stats or capture_feedback.

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

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

No guidance on when to use this tool versus alternatives, such as feedback_stats for statistics or capture_feedback for entering feedback. The description lacks usage context.

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

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

The description adds behavioral context beyond the 'destructiveHint' annotation by mentioning the re-inference of the lesson. However, it does not fully detail the irreversible nature of finalization or other side effects.

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

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

The description is a single sentence that efficiently conveys the core action and outcome, with no unnecessary words.

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

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

Given the simple tool with one parameter and a destructive annotation, the description adequately states the main purpose and action, but lacks warnings about irreversibility and does not explain the full implications of finalizing.

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 single parameter 'sessionId' is not described in the schema (0% coverage) and the tool description does not explain its purpose or how to obtain it, providing no added meaning.

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

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

The description clearly states the verb 'finalize' and the resource 'feedback session', and distinguishes it from siblings like 'open_feedback_session' by adding the action of re-inferring the lesson with follow-up context.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives, such as when to finalize versus open a session, or when to use 'infer_lesson_from_history' instead.

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 readOnlyHint=true already indicating safety, the description adds useful behavioral detail: it returns a decision of 'block' or 'allow', and on block the agent should surface the reason. It also clarifies that the tool evaluates the proposed call rather than executing it, which prevents misuse. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the primary purpose and immediate output semantics. It gives actionable usage guidance without redundancy or vague filler.

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

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

For a simple read-only policy check with two parameters and no output schema, the description adequately covers what the tool returns, when to use it, and its non-executing nature. It could optionally mention whether the policy is configurable, but given the schema and annotations, the description is sufficiently complete for agent 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 100%, with detailed examples for both tool_name and tool_input (e.g., {'command': 'rm -rf /'}). The description reinforces these examples in prose but does not add new parameter-level semantics beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states a specific action ('evaluate a proposed tool call against ThumbGate policy BEFORE executing it') and explicitly defines the two possible outputs ('block' with reason, or 'allow'). This clearly distinguishes it from sibling tools that approve, track, or enforce actions rather than pre-check 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 concrete when-to-use guidance: 'when about to run a shell command, write/edit a file, or take any irreversible action.' It does not explicitly name alternatives or exclusions, but the timing (BEFORE executing) and action categories are clear enough for an agent to select this tool appropriately.

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

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

The readOnlyHint annotation already indicates no destructive behavior. The description adds the context of 'dynamic' and 'decision-ready pulse' but does not disclose specifics like auth requirements, rate limits, or output size. It is consistent 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 sentences without waste. The first sentence is somewhat generic but the second provides concrete data sources and output elements. Could be more information-dense but not overly verbose.

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

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

With readOnlyHint and full schema coverage, the description covers the tool's purpose and input. However, without an output schema, the description could have elaborated on the structure of the 'pulse' (e.g., fields, format). Mentioning metrics, evidence, and next actions partially fills this need.

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%, so parameters are fully described in the schema. The description adds no additional meaning beyond what the schema provides for the parameters. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates operator artifacts from ThumbGate data, producing decision-ready pulses with metrics, evidence, and next actions. This specific verb-resource combination and data sources distinguish it from sibling tools.

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

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

No explicit when-to-use or alternatives are mentioned. Usage is implied from the purpose, but the description does not provide guidance on when not to use this tool or how it compares to siblings like dashboard or describe_reliability_entity.

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

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

The description discloses a behavioral edge case: 'Empty data returns insufficient_evidence,' which adds value beyond the readOnlyHint annotation. It doesn't contradict the annotation and gives the agent a clear expectation for empty results. No other behavioral traits like rate limits or error handling are mentioned, but the annotated read-only nature is already covered.

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: the first front-loads the core functionality with a clear verb and metric list, and the second adds a concise edge-case behavior. No filler 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?

For a no-parameter tool with a read-only annotation and an output schema, the description covers the operation and a specific edge case. It doesn't explain return values, but the output schema handles that. The only gap is lack of contextual differentiation from get_task_outcomes, but that's a usage guideline issue, not 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 tool has zero parameters, so the schema is trivially complete. The description doesn't need to explain parameters, and the baseline of 4 applies. No additional parameter semantics are required.

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 'compute' and names the resource 'metrics from recorded task outcomes,' clearly identifying the tool's function. It lists concrete metric categories (task, tool, safety, escalation, latency, cost, business), which prevents confusion with sibling tools like get_task_outcomes, though it doesn't explicitly call out 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 no guidance on when to use this tool versus alternatives. There is no mention of alternatives, exclusions, or prerequisites, leaving the agent to infer that it's for computing metrics, which tautologically follows from the purpose.

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 readOnlyHint=true, and description aligns with 'Return'. No additional behavioral context beyond the obvious read operation, which is acceptable given annotation coverage.

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 10 words, efficiently conveys purpose with no waste. Ideal conciseness.

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

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

Minimal but complete for a simple read-only tool with no parameters or output schema. Could be more explicit about return structure, but sufficient given low complexity.

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

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

No parameters exist, and schema description coverage is 100%. Description does not need to add param info; baseline 4 applies 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?

Description clearly states the tool returns active branch and release governance state, with a specific verb and resource. Distinguishes from sibling 'set_branch_governance' but could add more detail on what 'release governance state' entails.

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

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

No guidance on when to use this tool vs alternatives like 'set_branch_governance' or other governance tools. Implied usage from name, but missing explicit 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 readOnlyHint=true. Description adds what data is returned, which is useful context. However, no additional behavioral traits (e.g., speed, side effects) are disclosed.

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

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

Single sentence, no wasted words. Clearly communicates the tool's output.

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

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

Tool is simple with no parameters and no output schema. Description adequately names the returned items but does not detail their structure or format. Adequate but not complete.

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

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

The tool has zero parameters, so schema coverage is 100%. Baseline for 0 parameters is 4; description adds nothing about parameters, but none are needed.

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

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

Description clearly states the tool returns 'active task scope' and 'unexpired protected-file approvals', which are two specific pieces of state. Verb 'Return' is appropriate. While it doesn't explicitly differentiate from siblings like set_task_scope, the read-only nature is implied.

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

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

No guidance on when to use this tool versus alternatives such as set_task_scope. No when-to-use or when-not-to-use information is provided.

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

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

Annotations already declare readOnlyHint=true, and the description aligns by stating 'Read'. It adds behavioral nuance by describing the fallback to 'most recent evidence-backed outcome receipts' when taskId is not used, which provides context beyond the annotation. However, it does not clarify what 'evidence-backed' entails or how limit affects results.

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

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

The description is a single, front-loaded sentence that begins with the verb 'Read'. Every word adds meaning; there is no fluff or redundancy. It is an exemplar of concise writing.

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

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

The tool is simple with two optional parameters and no output schema, but the description still feels incomplete. It leaves the 'limit' parameter unexplained and does not mention what the returned receipts look like. Given the lack of output schema and param descriptions, the text should clarify these aspects to be fully 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%, so the description must compensate. It explains taskId implicitly through the 'by taskId' clause and the fallback behavior, but never mentions the 'limit' parameter at all. The agent is left guessing whether limit controls pagination, number of receipts, or something else. This is a significant gap.

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

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

The description uses the specific verb 'Read' and names the resource 'task outcome', clearly distinguishing the two operation modes: by taskId or most recent evidence-backed receipts. It differentiates from sibling tools like record_task_outcome (write counterpart) and get_agent_outcome_metrics (aggregate metrics).

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

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

The description implies the tool is for reading task outcomes but does not explicitly state when to use it versus alternatives, nor does it provide exclusions. It mentions two selection modes, giving some contextual guidance, but lacks direct comparisons to sibling tools.

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

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

The annotation already provides readOnlyHint=true. The description adds that approval decisions are deliberately absent from the agent tool surface, which is important behavioral context beyond the annotation. It does not contradict the annotation, and it clarifies the tool's safety and limitation.

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, front-loaded with the main purpose, and every sentence adds value. No redundant or extraneous wording.

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

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

The description covers the core purpose and a key limitation, but it omits any details about return format, pagination, or filtering behavior. Since there is no output schema, the agent has no way to know what the response looks like, which is a notable gap.

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

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

Schema coverage is 0%, and the description provides no information about the limit or status parameters. The agent must infer meaning from parameter names and enums, which is risky without explicit guidance. 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 'List auditable human-escalation state' with a specific verb and resource. It also differentiates from approval-related tools by noting that approval decisions are deliberately absent, which distinguishes it from siblings like request_human_escalation and approve_protected_action.

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

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

The description gives clear context for when to use the tool (auditing escalation state) and explicitly excludes approval decisions, serving as a 'when-not' guideline. However, it does not name alternative tools or provide concrete usage scenarios, so it lacks full explicit alternatives.

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

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

The readOnlyHint annotation already declares read-only behavior, so the description doesn't need restate that. The description adds useful context by noting the append-only nature of the ledger and the human-review queue, implying this is a projection over those. However, it doesn't disclose pagination behavior (limit parameter exists) or what 'projected' means for the returned states.

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 one concise sentence with no filler. It's appropriately front-loaded with the purpose. Could arguably add a bit more guidance about parameters, but the brevity itself is a strength.

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

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

With no output schema and no parameter documentation, the description leaves the agent to guess what 'projected' states look like, the format of the response, how 'status' filters work, and pagination semantics. The append-only ledger concept is mentioned but not explained. For a list tool with 2 undocumented params and no output schema, this is under-specified.

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

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

With 0% schema description coverage and only 2 parameters, the description adds no information about either parameter. The 'limit' (1-100) and 'status' (free-form string) parameters are completely undocumented in both the schema and description. However, the tool name and properties make the semantics reasonably guessable, so it's not a severe 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 ('List') and resource ('purchase-requisition states'), and adds context about the data source ('append-only financial ledger and human-review queue'). This distinguishes it somewhat from sibling tools like create/settle/reconcile purchase requisition, though it doesn't explicitly name alternatives. The term 'projected' is slightly ambiguous but conveys approximation.

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 some context (ledger + review queue as sources) but no explicit when-to-use or when-not-to-use guidance. With 47 sibling tools including clearly related ones (create_purchase_requisition, settle_purchase_requisition, reconcile_purchase_ledger), it doesn't state when selecting list vs. these alternatives is appropriate. There is no exclusion language or explicit alternative naming.

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

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

Annotations already indicate destructiveHint: true. Description adds that follow-up messages are captured for 60 seconds. No contradiction, but does not discuss other effects like session lifecycle or permissions.

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

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

Two succinct sentences. Front-loaded with the key action and condition. No unnecessary words.

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

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

Covers the basic purpose and temporal constraint. Lacks details on how feedbackEventId relates to previous capture, the role of signal, or what happens after 60 seconds. Adequate but with gaps.

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

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

Schema coverage is low (33%). Description does not elaborate on parameters (feedbackEventId, signal, initialContext). The timing detail is helpful but not linked to params.

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

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

Clearly states it opens a feedback session after thumbs up/down. Distinguishes from siblings like capture_feedback and finalize_feedback_session by implying it's a follow-up step, but does not explicitly differentiate.

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

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

Provides context to use after thumbs up/down, but no explicit when-not-to-use or alternative tools. The sibling list includes many feedback tools, but no guidance on selection.

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

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

The annotations already provide destructiveHint: true, alerting the agent to potential side effects. The description adds no additional behavioral context beyond the annotation—it does not disclose what 'execute' entails, whether it modifies the system, how it handles failures, or what side effects may occur. With the annotation present, the description misses the opportunity to enrich the agent's understanding of the tool's behavior.

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

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

The description is a single sentence, front-loaded with the action ('Execute'), and contains no filler. It efficiently conveys the tool's purpose and examples without redundancy.

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

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

For a complex tool that executes parallel workflows, the description is too thin. It does not mention what the tool returns, how results are surfaced, or what happens after execution. With no output schema, the description should at least hint at outputs or follow-up actions. It also does not clarify whether this tool initiates background work or blocks until completion, which is relevant given sibling tools like get_task_outcomes.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description's mention of example objectives aligns with the 'objective' parameter but adds no new meaning about timeoutMs or concurrency. Baseline 3 is appropriate because the schema carries the 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 clearly states the tool 'execute[s] a parallel, multi-step subtask workflow to resolve an objective', using a specific verb and resource. It provides concrete examples (security audit, performance benchmark, repository inspection) that illustrate the intended scope, though it does not explicitly differentiate from sibling tools like the many plan_* tools.

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

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

The description implies usage when an objective can be decomposed into parallel subtasks, giving example domains. However, it lacks explicit guidance on when to use this tool versus alternatives, such as the plan_* siblings or simpler single-task tools. No exclusions or prerequisites are stated.

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

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

The description accurately represents the tool as a read-only evaluation, aligning with annotations (readOnlyHint=true). It adds behavioral detail by specifying the outputs (recommendations on patterns, evals, fixes, safeguards), which is useful beyond the annotation alone.

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

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

The description is a single sentence that efficiently conveys the tool's purpose and key outputs. It is concise and front-loaded, though slightly dense. It could benefit from minor structural separation, but it earns its place.

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

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

Given the complexity (15 parameters, no output schema), the description provides a high-level overview but lacks detail on the exact format or nature of the recommendations. While parameters are well-described in schema, the absence of output schema means the description should offer more clarity on return structure, which it does not fully address.

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 is 3. The tool description does not add any additional meaning or context to the parameters beyond what is already provided in the schema. No parameter-specific elaboration is given.

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

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

The description clearly states it evaluates an agent workflow before adding tools, autonomy, or subagents, and specifies the recommendations (single-agent vs manager/decentralized patterns, evals, fixes, safeguards). This distinguishes it from sibling planning tools like plan_intent or plan_multimodal_retrieval which focus on different aspects.

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

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

The description explicitly states when to use the tool ('before adding tools, autonomy, or subagents'), providing clear context for its application. It does not, however, mention when not to use it or list alternative tools, so it lacks explicit 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?

Description says 'Prepare' which implies creating/writing, contradicting readOnlyHint=true annotation. No additional behavioral context provided (e.g., auth, side effects).

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

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

Single sentence front-loaded with purpose, though the contradiction reduces overall value. Still concise and structured well.

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

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

No output schema, 5 parameters, but description lacks detail on process, return format, or how components are prepared. Contradiction with annotations further undermines 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?

Schema coverage is 100%, so baseline is 3. Description merely lists components already covered by parameters, adding no new semantic depth.

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

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

Description clearly states the tool prepares specific ad components (intent clusters, ad copy, etc.) for ChatGPT Ads Manager tests, using a specific verb 'prepare' and a clear resource, distinguishing it from other plan_ 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?

Description implies use when setting up ads but lacks explicit guidance on when to use versus alternatives, no exclusions or prerequisites 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?

The readOnlyHint annotation already signals a safe read operation, and the description adds behavioral context about what the tool reports (savings and recommendations). No contradictions with annotations. However, details about how the estimate is computed or what 'proof-preserving' entails are absent, so the description doesn't fully disclose behavior.

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

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

The description is a single sentence that front-loads the core purpose ('Estimate footprint') and lists key outputs. It is compact with no filler, though the density of specialized terms makes it less immediately readable than a plainer rewrite. Still, every word earns its place.

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

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

With 9 parameters, a nested object, and no output schema, the description is brief. It names the three report types (progressive-discovery savings, context compaction savings, proof-preserving recommendations) but does not explain their format or relationship to the parameters. The readOnly annotation and full schema coverage mitigate the gap, making it minimally viable but not comprehensive.

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

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

Schema description coverage is 100%, with each parameter having a descriptive explanation (e.g., targetReduction default, matryoshkaOptions constraints). The description itself adds no parameter-level details, but with full schema coverage, the 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 uses a specific verb ('estimate') and identifies the resource ('MCP schema and feedback-context footprint'), distinguishing it from sibling planning tools like plan_multimodal_retrieval by focusing on context footprint rather than retrieval or readiness. However, terms like 'progressive-discovery savings' and 'proof-preserving recommendations' are jargon-heavy and not fully defined, slightly reducing clarity.

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

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

The description explicitly states when to use the tool: 'before loading large manifests into an agent prompt,' which is a clear situational trigger. It does not name alternatives or when-not-to-use scenarios, but the sibling tools suggest this is a planning/estimation aid rather than an execution tool. This meets the 'clear context, no exclusions' bar.

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

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

Annotations declare readOnlyHint=true; the description adds that the tool plans but does not execute or require GPU training. However, it does not disclose other behavioral aspects like idempotency or side effects. With annotations covering safety, the description adds moderate value.

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

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

The description is a single sentence that efficiently conveys the tool's purpose and scope. It is front-loaded with the key action ('Plan') and resource. Could be slightly more structured but is not verbose.

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

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

With 6 parameters and no output schema, the description should explain what the output or result looks like (e.g., a retrieval plan or recommendation). It lacks this information, leaving the agent uncertain about what to expect when 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?

Schema description coverage is 100%, so parameters are already well-documented. The description only lists example evidence types (screenshots, PDF pages), which partially overlaps with the 'evidenceTypes' parameter. No additional semantic information beyond schema.

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

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

The description clearly states the tool's purpose: 'Plan a high-ROI multimodal retrieval rollout.' It specifies the resource (multimodal retrieval for screenshots, PDF pages, etc.) and distinguishes from siblings by being a planning tool (not execution or retrieval). The phrase 'without starting GPU training' adds specificity.

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

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

The description implies when to use (planning a retrieval rollout without GPU training) but does not explicitly state when not to use it or suggest alternatives. No comparison to sibling tools is provided. The guidance is adequate but minimal.

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

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

Annotations already mark it as read-only (readOnlyHint=true). The description adds that it avoids spammy contributions, which is positive but not deeply behavioral. It does not disclose other traits like external API calls, ranking methodology, or side effects.

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

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

The description is a single, well-structured sentence that front-loads the main action and purpose. Every word earns its place with no redundancy or filler.

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

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

Given the complexity (4 parameters, no output schema), the description is adequate but incomplete. It does not explain the output format (e.g., how opportunities are ranked, what fields are returned). An agent would need additional context to effectively use the results.

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

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

Schema coverage is 100% with each parameter described in the input schema. The description does not add meaning beyond the schema; it merely restates the overall purpose. Thus, baseline score of 3 is appropriate.

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

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

The description clearly specifies the action ('Rank') and the resource ('upstream GitHub repositories ThumbGate depends on') for a distinct purpose ('proof-backed issue, bounty, and PR opportunities without spammy drive-by contributions'). It differentiates from siblings like 'search_thumbgate' by emphasizing planning over searching.

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 context (ranking for opportunities) but does not explicitly state when to use this tool versus alternatives like 'search_thumbgate' or when not to use it. No when-to-use/when-not-to-use guidance is provided.

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

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

The annotation declares readOnlyHint: true, and the description is consistent with a read-only mapping/planning operation. However, the description does not add deeper behavioral context beyond the high-level purpose, such as side effects, prerequisites, or invariant guarantees.

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

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

A single, well-structured sentence that front-loads the action and lists key dimensions. No redundant information; every word earns its place.

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

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

Given 14 parameters (all optional) and no output schema, the description is too terse. It does not explain what the tool produces (e.g., a report, a plan, a set of gates) or how the parameters influence the result. The agent lacks information to fully understand the tool's role in a workflow.

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%, so baseline is 3. The description adds value by grouping the boolean parameters into a 'PARE-style' framework, giving higher-level meaning (e.g., hasStateMachine, hasActiveUserSimulation are part of the mapping). This goes beyond the schema's atomic 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 uses a specific verb 'Map' and clearly identifies the resource 'proactive-assistant eval gaps' and the target 'PARE-style...gates'. It lists distinct aspects (state-machine, active-user-simulation, etc.) and stands out among siblings, which are a diverse set of tools.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. No explicit context, exclusions, or alternative tools are mentioned, leaving the agent to infer usage solely from the purpose.

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

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

The description aligns with the 'readOnlyHint': true annotation, confirming no side effects. It adds value by enumerating specific patterns detected, which goes beyond the annotation. However, it does not describe any additional behavioral traits like performance or data requirements.

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

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

The description is a single concise sentence that lists clear patterns, with no redundant information. It is front-loaded and 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?

While the description explains the tool's purpose and detection scope, it omits details about the output format (e.g., whether it returns a boolean, report, or risk score) and how to interpret results. Given the lack of an output schema, this is a notable gap.

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

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

Schema coverage is 100% with all parameters described. The description does not add specific parameter-level details beyond the schema, so it meets the baseline. The overall tool purpose helps contextualize the parameters but does not enhance their semantics.

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

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

The description clearly states the verb 'detect' and the specific resource 'reward-hacking patterns,' listing distinct types. This differentiates it from sibling tools like 'plan_proactive_agent_eval_guardrails' or 'verify_claim' which focus on different aspects.

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

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

The description implies usage for detecting reward hacking but does not explicitly state when to use this tool over alternatives. No guidance on prerequisites, when not to use, or comparison with siblings like 'verify_claim' or 'plan_proactive_agent_eval_guardrails' is provided.

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

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

The annotation indicates destructiveHint=true, but the description does not elaborate on what might be destroyed or any side effects (e.g., overwriting existing rules). No additional behavior context beyond annotation.

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, but it lacks critical information about parameters and behavior. It is under-specified rather than effectively concise.

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

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

With two undocumented parameters, no output schema, and a destructiveHint annotation, the description fails to provide sufficient context for an agent to use the tool correctly. It does not explain what prevention rules are, how they are generated, or what the output format is.

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%. The description does not explain the two parameters (minOccurrences, outputPath) or their roles. 'minOccurrences' is vaguely implied by 'repeated mistake patterns', but no explicit semantic value added.

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 specifies a clear verb 'Generate' and resource 'prevention rules', with context 'from repeated mistake patterns'. It is distinguishable from other 'generate' sibling tools like 'generate_operator_artifact'.

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 guidelines on when to use this tool versus alternatives. No mention of when-not-to-use or related tools like 'generate_skill' or 'generate_operator_artifact'.

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

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

The description adds context about what is recalled (feedback, memories, prevention rules) and when to use it. Annotations already declare readOnlyHint=true, so the description's added value is moderate but non-contradictory.

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

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

Two sentences only: first states purpose, second gives usage guidance. No wasted words, perfectly 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 no output schema, the description explains the return purpose (inject past learnings) adequately. It covers purpose, usage, and parameter context, but could slightly expand on return format.

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

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

The input schema has 100% coverage for all three parameters with clear descriptions. The tool description does not add additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool recalls past feedback, memories, and prevention rules for the current task, using a specific verb and resource. It distinguishes itself from siblings like 'retrieve_lessons' by focusing on full context injection.

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

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

Explicitly instructs to call this at the start of any task to inject past learnings, providing clear context. However, it does not mention when not to use or alternatives like 'retrieve_lessons'.

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=true, and the description is consistent (a reconciliation is read-only verification). The description adds some context about what is verified (totals, stale reservations, status counts, hashes) which goes beyond the annotation. However, it doesn't disclose behavioral details like what happens when discrepancies are found, whether hashes are verified or just listed, or whether this has side effects such as marking stale reservations.

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

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

A single compact sentence conveys the tool's role efficiently, front-loading the core action. It's concise without being under-specified. Could potentially add a brief 'when to use' clause but remains 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?

For a 0-parameter tool with a readOnly annotation and no output schema, the description covers the basic purpose. But given the ledger integrity domain and the sibling landscape (check_operational_integrity, workflow_sentinel, verify_claim), it would benefit from clarifying what 'reconcile' produces or triggers, especially around stale reservation handling, to distinguish it from other integrity tools.

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

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

The tool has 0 parameters, so there's no schema to document. The baseline for 0-param tools is 4, and the description adequately explains what the tool does since no parameter guidance is needed.

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

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

The description states a specific action (reconcile) on a specific resource (purchase ledger) and lists the reconciliation aspects: totals, stale reservations, status counts, and tamper-evident hashes. However, it doesn't distinguish this from siblings like check_operational_integrity or workflow_sentinel, which could plausibly serve overlapping audit/reconciliation purposes.

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

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

No guidance is provided on when to run reconciliation versus alternatives such as check_operational_integrity or verify_claim. The description implies a periodic/final reconciliation use case ('stale reservations') but never states it explicitly or names alternative tools for related integrity checks.

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

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

The annotation destructiveHint=true already signals a write operation. The description adds valuable behavioral context: idempotency (safe retries) and the rule that a completed response without evidence is recorded as not working. This goes beyond the annotation and clarifies side effects without contradiction.

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

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

The description is two sentences long, front-loaded with the verb and core purpose, and contains no fluff. The second sentence adds a critical behavioral rule that 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?

Despite being concise, the tool is complex (16 parameters, 7 required, nested objects). The description provides only a high-level summary and one edge-case rule. It does not explain required fields, status semantics, or how the components interrelate, leaving a significant gap for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It only lists high-level categories (verification, toolCalls, policy, efficiency, businessOutcome) that map to some nested objects, but it omits essential fields like taskId, goal, and status, and provides no structural or format guidance for the 16 parameters. This is insufficient for a tool with zero parameter descriptions 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 'Record' with a clear resource 'task-level outcome' and enumerates the included data categories (verification evidence, tool correctness, policy behavior, latency, cost, business KPI movement). This clearly distinguishes it from sibling read tools like get_task_outcomes.

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

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

The description implies the tool is for recording task outcomes after verification, and the idempotency note suggests retry safety. However, it does not explicitly contrast with alternatives or state when not to use it, though the context is clear enough for an agent to infer its primary use.

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

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

The description is consistent with the 'readOnlyHint' annotation, indicating a read-only analysis. It adds value by specifying the output (proposed rule and recurrence info), going beyond the annotation to describe the analysis nature. No contradictions.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose and output. Could be slightly expanded for completeness but remains concise.

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

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

While the description states the output (rule and recurrence), it lacks detail on how the analysis works or what recurrence info entails. With no output schema, more context would improve completeness. However, it's adequate for a focused analysis tool given sibling 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 coverage is 100% with clear parameter descriptions (conversationWindow, context, whatWentWrong, feedbackEventId). The description does not add significantly beyond the schema, but the schema itself is sufficient. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool performs a post-mortem analysis on negative feedback and returns a proposed rule with recurrence info. It uses a specific verb ('run') and resource ('post-mortem analysis on negative feedback'), distinguishing it from sibling tools like 'capture_feedback' or 'feedback_stats'.

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 analyzing negative feedback to generate rules, but provides no explicit guidance on when to use this tool versus alternatives like 'feedback_summary' or 'capture_feedback'. No exclusions or when-not-to-use context is given.

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

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

Annotations already mark destructiveHint=true. Description adds that it auto-files with system context, which is useful. No contradiction, though more detail on side effects (e.g., persistence) could help.

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

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

Two sentences with no wasted words. First sentence states purpose and scope, second sentence gives usage context. Front-loaded and 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 simplicity of the tool and no output schema, the description is sufficient. It covers purpose, scope, and when to use, though return behavior is not described.

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 provides 100% coverage with clear descriptions for each parameter. Description adds no additional semantic information, meeting the baseline.

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

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

Clearly specifies the action (report), the target (ThumbGate itself), and distinguishes it from project feedback. Mentions auto-filing GitHub issue, which further clarifies functionality.

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?

Explicit usage cue: 'Use when the user expresses frustration or requests a feature for the thumbgate tool.' Implicitly excludes project feedback but doesn't enumerate alternative tools for that case.

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 destructiveHint=true annotation already signaling write potential, the description adds meaningful behavioral context: idempotency, expiring nature, requester identity, and the self-approval restriction. It does not detail response behavior or authorization requirements, but adds substance beyond the annotation.

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

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

Two sentences are tightly packed with useful information. The most important action and constraints come first, with zero 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?

For a complex tool with 9 parameters, nested objects, no output schema, and only a destructiveHint annotation, the description provides a solid overview but lacks details on return values, error handling, or how the idempotency/expiration behave in practice. It is adequate but 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 0%, so the description must compensate. It explains the purpose of requester and evidence parameters, and hints at idempotencyKey and ttlMs via 'idempotent' and 'expiring.' However, several parameters (taskId, reason, severity, requiredReviewerRole, approvalContextDigest) receive no added meaning, leaving a gap.

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

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

The description uses a specific verb 'create' and a clear resource 'human-review request', while adding key attributes like idempotent, expiring, requester identity, and evidence. It distinguishes this tool from siblings like list_human_escalations and satisfy_gate.

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 requesting human review but does not explicitly state when to use this tool versus alternatives like satisfy_gate or approve_protected_action. The note that agents cannot approve their own requests provides a usage restriction, but no explicit guidance on alternatives or exclusions.

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

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

Annotations declare readOnlyHint=true, and the description describes a verification/gating behavior which is read-only, so no contradiction. However, the description says 'Blocking response when evidence is missing' — this describes the response format but doesn't disclose what happens to the agent's session on a blocking decision, whether the gate persists state, what the blocking flag means downstream, or auth requirements. For a gate tool with no output schema, the behavioral burden is high and it only partially covers return 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?

The description is a single dense paragraph but front-loaded with the core purpose ('Leader-Agent completion gate'). Each clause adds value: the evidence requirement, the factual claim recheck, the blocking behavior, and caller expectations. Slightly dense but no wasted words.

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

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

The tool has 4 params including a nested object (goalContract) with 6 sub-fields — moderately complex. The description explains the gate concept and mode but doesn't clarify the return value shape (no output schema present, so this cannot be inferred). It also doesn't clarify the relationship with sibling tools like satisfy_gate or verify_claim, which appear to overlap. For a gate-decision tool, the return semantics and downstream implications are under-specified.

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 is 3. The description does add value by explaining the mode semantics (blocking vs advisory) beyond the raw enum, and by framing claim as 'completion claim text to verify' with examples. The goalContract nested object is well-covered by the schema's own per-field descriptions, so the description adds little beyond referencing 'agent handoff contract' context.

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

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

The description clearly states this is a 'Leader-Agent completion gate' that requires evidence before declaring done/fixed/shipped/resolved, and verifies factual claims. It's specific about the verb (require/recheck) and resource (completion claims/evidence). It doesn't explicitly distinguish itself from sibling tools like satisfy_gate, verify_claim, or gate_check, though the completion-gate framing does suggest a distinct role.

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 when to use it: 'Before any agent declares done/fixed/shipped/resolved' and clarifies the caller behavior ('callers honor the blocking flag to stop completion claims'). It implicitly excludes the after-the-fact verification role of verify_claim, but doesn't explicitly name when NOT to use it or suggest alternatives for non-completion gates.

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

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

The destructiveHint: true annotation signals this tool has side effects (consuming/reserving funds). The description adds relevant context by noting approval is 'independently approved' and unavailable from the agent surface, which helps set expectations. However, it doesn't explain what 'reserve' does concretely—whether it's reversible, whether settlement follows, or what happens to unspent reserves. The 'single-use' qualifier adds some value beyond the annotation.

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 waste. It front-loads the core purpose and adds one critical constraint (approval unavailable from agent surface). 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 financial mutation tool with destructiveHint=true, 7 parameters, and no output schema, yet the description is only two sentences. It doesn't explain reserve lifecycle (does settlement follow?), TTL semantics, idempotency guarantees, failure behavior when funds are insufficient, or whether reserve is irreversible. For a money-moving operation this is notably under-specified. The sibling set includes settle and reconcile tools, suggesting a multi-step lifecycle that the description doesn't help navigate.

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

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

Schema description coverage is 0%, so the description must compensate for 7 undocumented parameters. The description clarifies nothing about individual parameters—amountUsd, vendor, purpose, sourceMessageId, requisitionId, ttlMs, and idempotencyKey all rely purely on their names. However, several parameter names are reasonably self-explanatory (amountUsd, vendor, purpose), and the idempotencyKey hints at retry semantics. The ttlMs field meaning (time-to-live presumably) is left entirely implicit.

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 structure ('Reserve a single-use amount from an independently approved purchase requisition'), which clearly distinguishes it from siblings like create_purchase_requisition, list_purchase_requisitions, and settle_purchase_requisition. The scope is identifiable from the siblings, though the term 'reserve' could use more context about what reserving vs settling means operationally.

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

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

The description states that 'Approval is unavailable from the agent tool surface,' which is a useful exclusion note, but it doesn't explain when this tool should be used versus create/settle/list purchase requisition tools. There's no guidance on prerequisites (an approved requisition must exist first, presumably via create_purchase_requisition), no idempotency guidance, and no mention of when alternatives would be appropriate.

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

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

The annotation readOnlyHint=true already declares the read-only nature, and the description does not contradict it. The description adds minimal behavioral context beyond the annotation, such as the per-action guidance focus, but does not disclose any potential side effects, error modes, or rate limits. With annotations present, the bar is lower, but the description still adds limited value.

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 concise sentences that front-load the main purpose and add a clear usage note. Every sentence earns its place, with no unnecessary information or repetition.

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

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

The description covers the core purpose and usage context but does not explain return values (no output schema exists) or parameter interactions. The rich schema descriptions compensate somewhat, but the description alone is not fully complete for a tool with 9 parameters and nested objects.

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 high (89%), so the parameters are well-documented in the schema. The description does not add any parameter-specific semantics beyond what the schema already provides, earning the baseline score of 3.

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

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

The description clearly states the tool retrieves relevant lessons for a tool/action context, using the specific verb 'retrieve' and resource 'lessons'. It also mentions the intended use in PreToolUse hooks. However, it does not explicitly differentiate from sibling 'search_lessons' or other retrieval tools, so it lacks sibling distinction.

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

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

The description provides a clear usage context ('Use in PreToolUse hooks for per-action guidance'), which tells the agent when this tool is appropriate. It does not mention exclusions or alternative tools, but the context is specific enough for a 4.

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 destructiveHint=true, and description adds behavioral traits: evidence stored with 5-minute TTL, structured reasoning chained in audit trail. This provides useful context beyond annotations, though could elaborate on consequences of re-satisfying a gate.

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

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

Two sentences, front-loaded with core purpose. Every word earns its place; no redundancy. Efficient and clear.

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

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

Covers purpose, TTL, audit trail, and structured reasoning role. Does not mention output or prerequisites (e.g., gate must exist), but given no output schema and tool simplicity, it is sufficiently complete.

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

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

Schema coverage is 100% with parameter descriptions. Description adds meaning: evidence TTL and audit trail behavior for structured reasoning, which is not in the schema. This significantly aids correct 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?

Description clearly states 'Satisfy a gate condition' with verb 'satisfy' and resource 'gate condition'. It distinguishes from sibling gate tools like register_claim_gate (creates gates) and gate_stats (queries gates).

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?

Implies usage for satisfying a gate condition but provides no explicit guidance on when to use versus alternatives (e.g., register_claim_gate, require_evidence_for_claim). No when-not-to-use or prerequisites 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?

Annotations declare readOnlyHint=true, so the read-only nature is already known. The description adds a little context by specifying that results include linked data like prevention rules and gates, but it does not disclose behaviors such as default query behavior, scope handling, or inclusion of shared lessons.

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

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

The description is a single sentence that is front-loaded with the verb 'Search' and contains no waste. It provides essential information efficiently.

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

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

Given the tool's complexity (7 parameters, a nested scope object, and no output schema), the description is insufficient. It does not describe return format, how scope affects results, or how it compares to related search tools like retrieve_lessons, leaving significant gaps for an agent to infer.

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 71% (5 of 7 parameters have descriptions), but the tool description does not clarify the unannotated parameters (scope, category) or add any semantic meaning beyond what the schema provides. The description focuses on what is returned, not on parameter meaning.

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 ('Search') with a resource ('promoted lessons') and enumerates the returned data ('corrective actions, lifecycle state, prevention rules, gates, and next harness fixes'), making its purpose unambiguous and distinguishing it from siblings like retrieve_lessons.

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 retrieve_lessons or search_thumbgate. There are no explicit exclusions or context signals for choosing this tool.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds contextual detail about the nature of the search (raw state across feedback, memory, rules, documents), which helps set expectations for the type of data returned. It does not describe output format or any side effects, but those are not necessary given the annotation coverage.

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, information-dense sentence that front-loads the action and scope. It has no redundant words and every phrase ('raw', 'ThumbGate state', 'across feedback logs, ContextFS memory, prevention rules, and imported policy documents') 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?

Given moderate complexity (6 params, nested objects, no output schema), the description adequately frames when and why to use the tool. The schema handles parameter details, and the description covers the search domain and data sources. It doesn't explain result format or edge cases, but the tool is a search operation, so the information provided is sufficient for an agent to invoke it correctly.

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

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

The input schema provides 100% description coverage for all six parameters, including enums, a nested filters object, and defaults like queryRewrite. The description text itself does not add parameter-specific meaning beyond the schema, so the baseline of 3 applies per the rubric.

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

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

The description clearly identifies the tool's purpose: searching raw ThumbGate state across four specific sources (feedback logs, ContextFS memory, prevention rules, imported policy documents). The verb 'Search' is specific, and the scope distinguishes it from sibling tools like search_lessons or recall, which focus on different data domains.

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 about what data the tool covers (ThumbGate state across named sources), which implies when to use it. However, it does not explicitly mention alternatives or when not to use it (e.g., 'for lesson search, use search_lessons instead'). The absence of exclusions and the clear scope justify a 4 rather than a 3.

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

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

The description adds value beyond the readOnlyHint annotation by specifying that it aggregates multiple data sources into one call, implying no side effects. 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 sentences with no redundant information. The main purpose is stated first, followed by the key benefit of replacing multiple calls.

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

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

Given the simple parameter and no output schema, the description adequately explains what the tool does and its relationship to sibling tools. The mention of 'LangSmith-style report' provides output 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 coverage is 100% for the single parameter windowHours, with a clear description. The tool description does not add additional meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose as a unified observability rollup that aggregates feedback stats, gate stats, and context/provenance events. It distinguishes from sibling tools by explicitly saying it replaces separate dashboard/gate_stats/feedback_stats 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 indicates when to use this tool (instead of making multiple separate calls for dashboard, gate_stats, feedback_stats), but does not explicitly state when not to use it or provide alternative scenarios.

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

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

Annotations already declare destructiveHint: true, and the description confirms the tool modifies state by 'declaring or clearing' governance. However, it does not elaborate on specific side effects, permissions, or reversibility, adding minimal behavioral context beyond the annotation.

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

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

The description is a single, front-loaded sentence that efficiently communicates the core action and purpose. Every word contributes, with no extraneous information.

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

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

Given the tool's complexity (11 parameters) and lack of output schema, the description is minimally complete. It states the purpose but does not explain workflows, parameter interactions, or provide examples. It is adequate but leaves gaps.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters with descriptions. The tool description adds no additional parameter meaning, resulting in a baseline score of 3.

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

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

The description clearly states the verb 'declare or clear' and the resource 'branch and release governance', with a specific purpose of evaluating PR, merge, release, and publish actions against explicit workflow state. This distinguishes it from sibling tools like get_branch_governance and plan_agent_design_governance.

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 guidance on when to use this tool versus alternatives, such as get_branch_governance or plan_agent_design_governance. No prerequisites or context are mentioned, leaving the agent to infer 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 destructiveHint=true already signaling this is a state-changing operation, the description adds context about the 'declare or clear' dual behavior and the consequence of enabling file/diff comparisons. It does not detail side effects like overwriting existing scopes or auth requirements, but the annotation lowers the bar.

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

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

The description is a single, front-loaded sentence that effectively communicates the core action and purpose without filler. It could have been slightly more structured, but it is efficient and clear.

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

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

Given the complexity (9 parameters, nested objects, no output schema), the description is too terse to be complete. It does not explain the lifecycle of a scope, what 'clear' does to existing approvals, or how the workflowContract and ttlMs affect behavior. The schema covers parameters, but the overall operational behavior is underspecified.

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 is 3. The description does not add any parameter-level meaning beyond the schema; it only explains the tool's overall purpose, which is acceptable since the schema fully documents each field.

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

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

The description clearly states the tool's action ('Declare or clear the current task scope') and its purpose ('so ThumbGate can compare affected files and diffs against the approved path set'). This goes beyond the title and distinguishes it from siblings like get_scope_state or set_branch_governance.

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

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

The description implies when to use it (when you need to set or clear a task scope) and explains the benefit. However, it does not explicitly mention alternatives or when not to use it, such as referencing get_scope_state for reading the current scope.

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

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

The key disclosure 'Events are append-only' is valuable behavioral context beyond the destructiveHint annotation, informing the agent that operations are irreversible. The annotation already signals destructiveness, and description reinforces it without contradicting. No annotation contradiction detected.

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

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

Two sentences, zero waste. Each sentence earns its place: first defines the dual action, second discloses the append-only invariant.

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 6 parameters, 0% schema coverage, no output schema, and a destructiveHint annotation, the description is thin. It doesn't explain which parameters are required for each status branch (committed requires evidence+actualAmountUsd; released likely doesn't), the mutual exclusivity of the two actions, or the append-only consequence for callers. Sibling create/reserve/list tools suggest a lifecycle that isn't explained.

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 description carries the parameter burden. The description mentions 'receipt evidence' (mapping to evidence parameter) and 'actual spend' (mapping to actualAmountUsd), but doesn't clarify the relationship between status ('committed'/'released') and which parameters apply to each branch, or what reason/is used for.

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

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

The description uses specific verbs ('Commit actual spend', 'release an unused reservation') identifying two distinct actions coupled with 'receipt evidence'. It distinguishes the settle action from siblings like reserve_purchase_requisition and reconcile_purchase_ledger, though it could be clearer about the reconciliation relationship.

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

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

The description implies when to settle (commit with receipt evidence or release unused reservation) but doesn't explicitly state when NOT to use this vs siblings like reconcile_purchase_ledger or how it relates to reserve_purchase_requisition. No explicit exclusions or alternative tool names given.

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

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

Annotations already set readOnlyHint=true, so the description adds context about returning up to 3 ranked suggestions with source. However, it does not disclose behavior when no results are found or ranking details, leaving some transparency gaps.

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

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

The description is two sentences, front-loaded with the main purpose, and every word adds value. No redundancy or unnecessary details.

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

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

Given the simplicity of the tool and good schema coverage, the description adequately covers what the tool does, what it returns, and when to use it. It lacks mention of error handling or edge cases, but these are minor for a suggestion 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?

Input schema coverage is 100%, so the schema already describes the parameters well. The tool description does not add additional meaning beyond the schema, thus baseline score of 3 is appropriate.

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

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

The description clearly states the tool suggests corrective actions for failures by searching lesson DB and prevention rules. It uses a specific verb+resource structure, but does not explicitly differentiate from sibling tools like 'diagnose_failure' or 'search_lessons', though the combination of sources is implied.

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 includes an explicit usage context: 'Call this when something goes wrong and you need guidance on what to do next.' It provides clear when-to-use guidance but does not mention when not to use or alternative tools, meeting the score 4 criteria.

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?

Description adds expiry information beyond annotations ('Session actions expire after one hour'), but does not elaborate on the destructive hint (e.g., whether it overwrites previous actions, irreversibility, or required permissions). Annotations only provide destructiveHint=true without further 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?

Two sentences with no extraneous information. Purpose is front-loaded, and the expiry detail is a necessary addition. Every sentence adds value.

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

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

Given two parameters, one required, no output schema, the description covers core purpose, examples, and time-bound behavior. It assumes understanding of 'current session' (reasonable given sibling tools) but does not explain return value or error conditions. Acceptable for a simple recording 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 covers both parameters with descriptions (100% coverage). Description supplements with examples for actionId (figma_verified, tests_passed), adding meaning beyond the schema's 'Verification action ID'. Metadata parameter is not further elaborated.

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 verb 'Record' and resource 'verification action in the current session' with concrete examples (figma_verified, tests_passed). It distinguishes from sibling tools like record_action_receipt by emphasizing session scope.

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?

Implies use for session-scoped verification actions with expiry, but does not explicitly state when not to use or compare to alternatives like record_action_receipt. No explicit guidance on prerequisites or 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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: 'tiered graceful degradation (full → warm → cold)' and the combined data sources (session state, user profile, lessons, guards, context pack, code-graph impact). This gives insight into the tool's internal behavior without contradicting annotations.

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

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

Two sentences, no filler. First sentence states the core function, second provides key behavioral nuance and differentiation. Every word earns its place.

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

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

Given the tool's complexity (5 params, nested objects, no output schema), the description covers the purpose, combined data sources, degradation tiers, and relationship to siblings. It doesn't detail the return structure, but listing the components implies what the context object contains. Slight gap for a fully self-contained description.

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%, so the baseline is 3. The description doesn't detail individual parameters but provides an overarching conceptual model (e.g., 'code-graph impact' hints at repoPath) that slightly enriches understanding. Still, it doesn't add meaning beyond what the schema already specifies.

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 ('Assemble') and clearly defines the resource ('complete, role-aware context object'). It also distinguishes itself from siblings by stating it 'Replaces multiple recall/retrieve/session_primer calls' as a single orchestrated request.

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

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

The description clearly identifies when to use this tool: when a comprehensive, consolidated context is needed in one call, instead of making multiple recall/retrieve calls. However, it doesn't explicitly state when not to use it or mention lighter-weight 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 declare readOnlyHint=true, which is consistent with a verification tool. The description adds meaningful behavioral detail beyond the annotation: it discloses that the tool uses configured verifiers (SQLite/filesystem/JSON) and only rechecks 'parseable factual claims,' while showing that non-parseable claims (e.g., 'all tests pass') rely purely on tracked evidence. This granularity aids the agent in knowing what to expect.

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

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

The description is a single, dense sentence that packs purpose and behavioral nuance efficiently. It's front-loaded with the primary action. Slightly verbose phrasing ('for parseable factual claims (row counts, file lines/bytes/existence, versions)') but earns its length by clarifying what counts as parseable.

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 goalContract object and 2 parameters, but the description covers the core behavior well: what gets verified, how (verifiers), and when. No output schema exists, so the description doesn't need to explain return values. Given the moderate complexity and full schema coverage, the description is reasonably complete, though it doesn't specify what passing/failing output looks like or edge cases (e.g., unconfigured verifiers).

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%, so both parameters are documented in the schema. The claim param example ('the row count is 1,284') and goalContract description ('use this when a worker/orchestrator/reviewer loop needs explicit done criteria') add useful meaning beyond the raw schema. This is baseline-plus credit, but the description doesn't add much more semantic depth than the schema already provides.

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

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

The description clearly states the tool's purpose: it checks whether a claim has enough tracked evidence and rechecks SQLite/filesystem/JSON verifiers for parseable factual claims. The specific verb 'check/recheck' plus the resource ('claim', 'tracked evidence') distinguishes this from siblings like require_evidence_for_claim, gate_check, and satisfy_gate, though the distinction isn't explicitly drawn.

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 explains when to use it — before the agent asserts a claim — and distinguishes two cases: claims with tracked evidence, and parseable factual claims needing verifier rechecks. It does not explicitly name alternative tools or state when NOT to use it, but the context (verify claims before asserting) is reasonably clear.

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

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

The readOnlyHint=true annotation already signals this is a non-destructive read/prediction tool, and the description's 'predict... before execution' framing is consistent with that. The description adds value by disclosing the predictive/passive nature (predicts rather than enforces) and the scope (risk, blast radius, remediations). It does not disclose output format, but as a prediction tool with no output schema this is a minor gap given the annotation coverage.

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

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

The description is a single, dense sentence with zero wasted words. It packs the verb, resource, scope (workflow risk, blast radius, remediations), and timing (pre-action) into one efficient sentence. No fluff, no redundancy with the title.

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

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

This is a high-complexity tool with 26 parameters, many nested objects, and 6 workflow pattern enum values. No output schema exists to explain return values. While the 100% schema coverage and readOnlyHint annotation help, the description is quite thin for such a complex prediction tool - it doesn't mention what the output shape is, how it consumes the 26 available parameters, or any constraints on which parameter combinations are meaningful. For a tool this intricate, more contextual detail would be warranted.

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

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

Schema description coverage is 100%, so the schema already documents all 26 parameters well. The description itself adds no parameter-level meaning beyond what the schema provides. Following the calibration baseline for high coverage, this is a solid 3 - the schema does the heavy lifting and the description adds little parameter context, though the core concept (what inputs drive the prediction) could benefit from a sentence highlighting the key input parameters like toolName, params, and workflow.

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 'Predict pre-action workflow risk, blast radius, and remediations before a tool call executes' clearly states the verb (predict), the resource (workflow risk/blast radius/remediations), and provides timing context (before execution). It lacks explicit differentiation from siblings like prevention_rules or gate_check, though the 'workflow risk prediction' angle is somewhat distinct among the many planning/sentry tools.

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

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

The description implies it is used before a tool call executes ('pre-action', 'before a tool call executes'), which establishes timing context. However, it does not explicitly state when NOT to use it or name alternative tools such as prevention_rules, gate_check, or approve_protected_action for gate/enforcement scenarios. Given the 49 sibling tools, more explicit differentiation would help.

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