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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds context about merit factors and actions, including that 'assess' triggers a re-evaluation, which is behavioral. 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?

Three sentences are concise and front-loaded, efficiently stating purpose, listing actions, and adding context. No wasted words.

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

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

Given no output schema, the description adequately explains each action's outcome (view metrics, trigger assessment, list top agents). Minor omission of assess return details, but sufficient for tool usage.

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 has 100% coverage with descriptions. The tool description adds clarity to the 'action' enum by explaining each option, providing value beyond the schema.

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

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

The description clearly states the tool queries agent citizenship tier and merit score, listing three specific actions. However, it does not explicitly distinguish from sibling tools, though the purpose is specific.

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 each action (status, assess, leaderboard) and provides context about merit factors, but lacks explicit exclusions or alternative 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, destructiveHint=false, idempotentHint=true. The description adds context about automatic enforcement and manual exercise, but the term 'exercise' could imply mutation, which contrasts with the read-only hint. However, the listed actions are queries, so no direct contradiction. The description adds moderate value beyond annotations.

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

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

The description is concise at three sentences, front-loading the core purpose. The only minor drawback is the ambiguous phrase 'manual exercise' given that actions are queries, but overall 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?

The description covers the tool's role within Colony Phase 3 and automatic enforcement, and parameter dependencies are specified. However, it lacks any explanation of the output format or error scenarios, which would be useful since there is no output schema. For a simple query tool with high schema coverage, this 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 100%, with each parameter described. The description adds contextual hints beyond the schema, such as noting that institution_id should come from board_list_institutions or board_list_charters, and clarifying which parameters are required for each action. This improves usability over raw schema descriptions.

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

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

The description clearly states the tool's purpose: querying and exercising constitutional agent rights within Colony Phase 3. It enumerates two specific actions (query_rights and explain_rejection) with brief explanations, differentiating it from sibling tools like agent_citizenship_status or approve_gate that deal with other 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 provides clear guidance on when to use each action: query_rights for viewing rights and explain_rejection for gate rejection explanations. It also notes that rights enforcement is automatic, framing this tool as for visibility and manual exercise. However, it does not explicitly exclude scenarios or mention alternatives, making it slightly less than a 5.

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

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

Annotations indicate non-destructive, non-idempotent behavior. The description adds that it is a 'human-in-the-loop mechanism' but does not detail side effects, required permissions, or what happens after approval/rejection. With no output schema, the absence of return value info is a gap.

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 the verb and objective. Every word is meaningful; no redundancy or fluff.

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

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

The description is minimal and does not mention return values or additional effects (e.g., confirmation, errors). Given the lack of output schema, more detail on output or post-conditions would improve completeness. However, the tool's simplicity partly compensates.

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 has 100% parameter description coverage. The description adds value by clarifying conditional behavior: gate_id is required for approve/reject but not for list (implied by 'Lists pending gates if no gate_id provided'). This goes beyond the schema's static 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 explicitly states the tool's purpose: 'Approve or reject a pending MANDATORY gate decision' and 'Lists pending gates if no gate_id provided.' It distinguishes this from siblings like board_approve_gate and srt_approve_repair by highlighting the MANDATORY and human-in-the-loop aspect.

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

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

The description provides clear usage context: 'Lists pending gates if no gate_id provided' and implies that approve/reject require a gate_id. However, it does not explicitly mention when to use alternatives or when not to use the tool. The action enum partially covers this, but explicit guidance is missing.

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, destructiveHint=false, and idempotentHint=true, so safety profile is clear. The description adds valuable context: the classification is heuristic, not a legal determination, and it returns governance recommendations. This goes beyond annotations by disclosing limitations and additional outputs.

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

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

The description is three sentences long, each providing essential information: purpose, categories, return value, and a caveat. It is front-loaded with the core action and wastes no words. Every sentence earns its place.

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

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

Given the absence of an output schema, the description adequately explains what is returned (tier and recommendations) and lists the categories. With 100% schema coverage for inputs, the description covers the essential aspects. However, it could briefly mention how the heuristic works (e.g., based on flags like autonomous_decisions) to be 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?

The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description does not add per-parameter details beyond what the schema provides. It offers high-level context but does not enhance the semantic meaning of individual parameters.

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

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

The description clearly states the tool's function: assessing risk tier using rule-based mapping to EU AI Act categories, listing the possible categories (Unacceptable, High, Limited, Minimal). It also specifies the return value (tier and MAI governance recommendations). This is specific and distinct from sibling tools like 'classify_decision' or 'score_governance', which focus on different classification tasks.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives. It implies context (EU AI Act classification) but does not state when it is appropriate or when to avoid it (e.g., if a legal determination is needed). 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?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, establishing safety profile. Description adds that it returns a hash-chained audit trail with MAI classification, which provides slight behavioral context beyond annotations.

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

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

Two concise sentences: first states the core purpose, second adds key details about return format. No redundant phrases, front-loaded with the main action.

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

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

Given 4 optional parameters, read-only annotations, and no output schema, the description provides sufficient context for a query tool. Mentions hash-chained trail and MAI classification, but could optionally note ordering or that results are recent.

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 detailed descriptions. The tool description adds no extra meaning beyond what the schema provides, so 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?

Description clearly states the tool queries the audit ledger for governance entries, providing two specific use cases: search by operation name or retrieve recent entries. It distinguishes from sibling tools like export_ledger and verify_ledger by focusing on querying return of hash-chained audit trail with MAI classification 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?

No explicit guidance on when to use this tool versus alternatives like export_ledger or verify_ledger. The description only states what it does without mentioning 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 indicate idempotentHint=true and readOnlyHint=false. Description adds that after approval, the session transitions to 'complete' and output becomes available. 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?

Four sentences, each essential. Front-loaded with purpose, followed by context, mechanism, and outcome. No redundant or filler content.

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

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

Tool is simple with 3 parameters, no output schema, no nested objects. Description covers purpose, trigger condition, post-approval state, and parameter context. Fully adequate.

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

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

Schema coverage is 100% with descriptive parameter names. Description adds minimal extra context, e.g., 'recorded in the forensic audit chain' for rationale. Baseline of 3 applies as schema already explains well.

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 approves a mandatory governance gate on a deliberation session. It distinguishes from siblings by specifying 'MANDATORY' and referencing the human-in-the-loop enforcement mechanism.

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 explains when to use: when a board session reaches 'pending-gate' status. It implies that without approval, the session cannot complete. No explicit alternative provided, but the context is clear.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds behavioral context: it creates a session (non-destructive), takes time, and returns a session_id. It does not contradict any annotations and provides valuable runtime expectations.

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

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

The description is concise, consisting of two sentences with no extraneous information. It front-loads the core action and provides essential details (runtime, output retrieval) efficiently. 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?

The tool has no output schema, but the description compensates by stating it returns a session_id and directing users to board_get_session for outputs. Combined with the detailed parameter descriptions and annotations, the description provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description adds semantic value by elaborating on the 'topic' parameter ('Be specific — this is what every seat will reason about') and explaining the 'context' parameter. This enhances an agent's understanding beyond the schema.

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

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

The description clearly states the tool's purpose: convene a governed deliberation session for a charter. It explains the concept of seats and modes, and distinguishes itself from the sibling tool board_get_session, which retrieves outputs. The specific verb 'convene' and resource 'session' are well-defined.

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

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

The description provides clear usage guidance: it explains the typical runtime (30–120 seconds) and directs users to board_get_session for retrieving results. However, it does not explicitly state when not to use this tool or list alternative tools beyond retrieval. Still, the context is sufficient for an agent to decide.

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?

Despite annotations already indicating readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral details: what is returned (seat positions, consensus, dissenting views, governance record) and polling behavior. 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 two sentences, front-loaded with the core purpose, and every sentence adds value. No wasted words.

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

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

Given the tool's three required parameters and no output schema, the description explains both the return fields and the polling behavior for running sessions. This is complete for a read-only retrieval 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 has 100% coverage with clear descriptions for each parameter. The tool description does not add additional meaning beyond what the schema provides, meeting the baseline expectation.

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

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

The description explicitly states 'Retrieve the status and output of a governed deliberation session', using a specific verb and resource. It clearly distinguishes from sibling tools like board_convene_session, which creates sessions.

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

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

The description provides context on when to use the tool (after convening a session) and includes polling advice for running sessions. It does not explicitly state when not to use it, but the guidance is clear and actionable.

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

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

Discloses the tool creates institutions with sealed charters, but does not mention reversibility, permissions, or idempotency beyond what annotations (destructiveHint=false) suggest.

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, efficient enumeration of kits with no redundant 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?

Adequate for a simple one-parameter tool with no output schema; could mention idempotency or failure behavior for repeated calls.

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

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

The description adds meaning beyond the schema's enum and param description by explaining each kit's composition and compliance alignment, making selection easier.

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 installs a prebuilt Institution Kit, lists three specific kits with their details, and distinguishes from siblings dealing with existing charters or institutions.

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 to set up governed org chart templates, but no explicit guidance on when to use this tool vs alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true, so the description aligns. It adds behavioral details beyond annotations by specifying the return fields (charter IDs, types, deliberation modes, etc.), which helps the agent understand what to expect. 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 two sentences: the first states the core action and scope, the second lists return fields and a usage hint. Every sentence adds value, and the most critical information is 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 adequately covers what the tool returns (charter IDs, types, deliberation modes, seat configurations, status) and provides a useful hint for the next step (convening sessions). This is complete for a list operation.

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

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

Schema coverage is 100% (institution_id described as 'from board_list_institutions'). The description does not add additional semantic information about the parameter beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists all charters under a governed institution, explicitly naming the resource (charters) and elaborating with examples (boards, committees, subcommittees). It distinguishes from sibling tools like board_list_institutions by focusing on charters, not institutions.

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 (list charters for a given institution) and hints at downstream usage ('Use charter_id to convene sessions'), but does not explicitly state when not to use this tool or contrast with alternatives like board_search_precedent.

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?

Adds context beyond annotations: describes institutions as governed bodies with charter hierarchy and explains return value. Annotations already cover safety and idempotency.

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 wasted words, front-loaded with purpose and key 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?

Completes the picture by stating return value and linking to usage (convening sessions), no output schema needed.

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

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

No parameters present, so schema coverage is 100% trivially. Description does not need to add parameter info, baseline 4.

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

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

Clearly states 'List all institutions' with specific examples (Architecture Review Board, Federal AI Board) and explains purpose. Differentiates from siblings like board_list_charters and board_convene_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?

Implies usage before board_convene_session by stating 'Returns institution IDs needed to convene sessions', but does not explicitly mention when not to use or provide alternatives.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds that it returns ranked cases with quality scores, gate approval status, and citation counts, and that it performs full-text search against prior deliberation agendas. This provides useful behavioral context beyond the annotations.

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

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

The description is concise at 4 sentences, each adding value. It is front-loaded with the primary purpose and then provides key details. No unnecessary words 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?

For a search tool with 3 parameters and no output schema, the description covers purpose, usage, parameter behavior, and return format (ranked cases, quality scores, approval status, citation counts). This is fully complete for an agent to use effectively.

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%; each parameter already has a clear description. The description adds context about full-text search for 'topic' and scope behavior for 'charter_id', but does not significantly improve upon the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool searches deliberation precedent (Colony Layer 1) for prior board rulings, with specific details about returned data (ranked cases, quality scores, gate approval status, citation counts). It includes a usage example for citing cases, distinguishing it from sibling tools like board_approve_gate or board_convene_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 explicitly frames the tool's use case: 'ground new deliberations in institutional case law.' It provides a citation format. While it does not mention when not to use it or name alternatives, the context is clear enough for an agent to decide when to invoke this tool versus others.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the three branches but does not reveal behavioral traits beyond what annotations provide. No 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 front-loaded with purpose and provides necessary details in 3 sentences. It is efficient but could be slightly more concise. Still good structure.

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

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

For a read-only query tool with no output schema, the description covers the actions and branch context well. It lacks return value details but is sufficient given schema richness and annotations.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context (e.g., explaining branches) but does not add semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it queries constitutional branch authority, with specific sub-actions (status, roster, violations) and explains the three branches. It distinguishes itself from sibling tools like agent_citizenship_status by its focus on separation of powers.

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 sub-actions, implying when to use each (e.g., 'status' for user's branches). However, it does not explicitly exclude cases or compare to siblings, leaving some ambiguity on when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows it's a safe read operation. The description adds that results are returned in causal order with hash-chain verification, providing valuable behavioral context beyond annotations.

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

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

The description is two sentences long with no redundant information. The first sentence states the main purpose and outputs, the second details format options. Every word contributes to understanding, making it 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 no output schema, the description partially covers the output by mentioning 'every link' and the specific elements returned. It could be more complete by describing the response structure or pagination (though limit parameter addresses the latter). Overall, it provides sufficient context for an intelligent agent.

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

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

Schema coverage is 100%, and the description adds significant value to parameters, especially the 'format' enum by explaining each option: 'summary' for overview, 'full' for all links, 'dag' for causal graph, 'export' for EU AI Act compliance artifact. This enriches the schema definitions with real-world use cases.

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 reconstructs the complete Chain of Reasoning for a session, agent, or time range. It lists the exact elements returned and format options, making its purpose unambiguous. It distinguishes itself from sibling tools like audit_pipeline or export_ledger by focusing on causal order and hash-chain verification.

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 how to use different formats ('summary', 'full', 'dag', 'export') but does not explicitly guide when to choose this tool over siblings. It lacks explicit when-to-use or when-not-to-use guidance, leaving the agent to infer based on the tool's 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 declare readOnlyHint, destructiveHint, idempotentHint. Description adds value by specifying return fields (classification level, confidence, gates, rationale) and mentions MAI framework, which is not in 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?

Single sentence that efficiently conveys purpose, framework, and output. No redundant or filler content.

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

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

No output schema exists, but description outlines return values. Covers key aspects for an AI agent to decide invocation, though could detail what 'gate requirements' means.

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

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

Schema has 100% description coverage for all 6 parameters. The description does not add additional meaning beyond what the schema already provides; baseline score applies.

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

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

Clear verb 'classify' with specific resource 'AI agent decision using the MAI Framework'. Distinct from siblings by focusing on classification into Mandatory/Advisory/Informational levels.

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 versus alternatives like assess_risk_tier or evaluate_threshold. Implied by purpose but no contextual differentiation.

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 annotations: it explains that actions are tier-gated (agents earn rights through merit). Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with the description's mix of read (list) and write (request, review) operations. 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 concise, consisting of three sentences. The first sentence states the overall purpose, the second breaks down the actions, and the third adds important context about tier-gating. No unnecessary words, every sentence earns its place.

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

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

The description covers the tool's functionality, actions, and authorization context. It lacks information about return values or error handling, but given the absence of an output schema, the description provides enough for an agent to understand how to invoke the tool correctly. The parameter descriptions in the schema fill in the rest.

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% description coverage with detailed parameter descriptions. The tool description adds semantic value by specifying which parameters are required for each action (e.g., institution_id and topic for request; request_id and decision for review). This helps agents understand conditional requirements beyond the schema's general descriptions.

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

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

The description clearly states the tool's purpose: 'Request, list, or review agent-initiated session convene requests.' It lists three specific actions (request, list, review) with brief explanations. The description differentiates from sibling tools by focusing on convene requests in a colony autonomy context, which is unique among the 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?

The description provides context on who can perform each action: 'citizen+ can request a governed session', 'elder+ approve/reject a request'. It also mentions tier-gating, guiding agents on eligibility. While it doesn't explicitly state when not to use this tool versus alternatives, the three actions are self-contained and cover the main use cases.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false. The description adds valuable context by explaining that the 'pulse' action triggers a fresh snapshot, implying a non-read side effect, and details the computation factors. This goes beyond the annotations.

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

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

The description is concise with two sentences. The first sentence states the overall purpose, and the second lists actions and composition. No wasted words.

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

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

The description provides enough context for the three actions and their outputs, though it does not detail the exact return format. Given the tool's simplicity and absence of output schema, it is adequately 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 descriptions for all parameters. The description reinforces the action enum and explains the 30-day default for trend but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: viewing colony health score, trend, or triggering a snapshot. It specifies three distinct actions (snapshot, trend, pulse), making it highly specific and easily distinguishable from sibling tools like system_status or phoenix_recovery_health.

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 lists the three actions and their meanings, providing clear guidance on when to use each. However, it does not exclude other tools or provide comparison with alternatives like system_status, so it lacks explicit when-not-to-use guidance.

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

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

Annotations indicate the tool is neither read-only nor destructive, and the description aligns with this. The description adds behavioral context by detailing role requirements for each action and that it serves as a petition mechanism. It does not contradict annotations.

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

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

The description is three sentences long: the first sets the tool's domain and available actions, the second details each action with role requirements, and the third adds a contextual note. It is front-loaded, concise, and every sentence carries essential information.

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

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

The description covers actions and roles but omits several contextual details: what happens after an action (e.g., post-suggest confirmation, review outcomes beyond roles), whether actions are reversible, or any expected output. Given the tool has 10 parameters and no output schema, more context on the workflow or return values 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 description coverage is 90%, so the schema already documents most parameters. The description repeats the action enum meanings already present in the schema (e.g., 'suggest = propose change') without adding new semantic value. It does not explain the meaning or usage of parameters like 'summary' or 'affected_sections' beyond what the schema provides, so no significant added value.

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

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

The description clearly states the tool's function: 'Colony Autonomy: Suggest, list, review, or upvote charter amendment suggestions.' It enumerates four distinct actions with specific roles and purposes, making the tool's purpose unambiguous and distinguishing it from sibling tools like 'colony_convene_request'.

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

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

The description provides explicit when-to-use guidance for each action by specifying the required roles: 'suggest (citizen+ ...)', 'list (view suggestions)', 'review (elder+ ...)', 'upvote (citizen+ ...)'. It also hints at alternatives by noting it's 'The petition mechanism for governed agents,' but does not explicitly state when not to use the tool.

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

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

Annotations are neutral (all false), but the description provides detailed behavioral rules: highest risk level wins, shortest TTL wins, roles intersect, trust level contaminates downward. This adds valuable context beyond annotations, making the tool's behavior transparent.

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

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

The description is a single concise sentence plus four clear behavioral rules. Every part is necessary and front-loaded. No wasted words.

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

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

Given the absence of an output schema and the tool's complexity (4 required params, composition logic), the description is too brief. It lacks prerequisites, edge-case handling, or what happens to original packs. While the core logic is explained, completeness suffers.

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 schema already describes each parameter. The description adds no extra semantic detail about individual parameters, 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?

Clearly states it composes multiple memory packs into a unified execution context. The verb 'compose' is specific, but the description does not explicitly differentiate from sibling tools like 'distill_memory_pack' or 'promote_memory_pack', so it does not fully distinguish.

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 vs. alternatives. An agent would need to infer usage from the name and description. No exclusions or alternative tools mentioned, which is a significant gap.

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

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

The description details behaviors beyond annotations: actions, tier thresholds, force override limits, gate types, cooldown, and no autonomous loop. No contradiction with annotations (readOnlyHint=false, destructiveHint=false) as compaction modifies state but description doesn't claim idempotence or harmlessness.

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 packed with useful detail in a structured format (actions, tiers, rules). It is front-loaded with the core purpose and then breaks down specifics efficiently 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?

Given the tool's complexity (4 params, enums, multiple actions) and no output schema, the description covers actions, parameters, behavioral rules, and constraints. It lacks only explicit return value details but explains action outputs (e.g., 'health + recommendation' for status).

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 each parameter. The description adds contextual value by explaining tier meanings (percentages and recommendation types) and force semantics, going beyond schema alone.

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

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

The description clearly states 'Governed context compaction' with specific verbs (detects, restores, compact, verify, history) and resource (context). It distinguishes itself from sibling tools like 'request_context' by focusing on compaction, not expansion.

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?

While it explains actions, tiers, and constraints (force, cooldown), it lacks explicit guidance on when to use this tool vs. alternatives like 'request_context' or general system tools. Usage is implied but not contrasted.

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 annotations by noting the draft is ephemeral and requires a mandatory gate, but lacks details on side effects or error 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?

Two sentences, front-loaded, with no unnecessary words; every sentence adds distinct information.

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

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

The description omits the return structure of the draft pack and does not explain what 'usage history' refers to, leaving some gaps for a tool with no output schema.

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

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

Input schema has 100% description coverage, so the description does not need to add parameter details. However, it adds no extra semantics beyond the schema.

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

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

The description clearly states the tool distills governance patterns from usage history into a draft heuristic pack, using a specific verb and resource, and differentiates from siblings like approve_gate and promote_memory_pack.

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 the output is ephemeral and requires a mandatory gate for production, providing context on when to use, but does not explicitly exclude scenarios or name alternative 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 indicate read-only, idempotent behavior. The description adds value by specifying return values (rate, status, recommendations) and the caveat that the healthy band is a design heuristic.

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

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

Three sentences are efficient and front-loaded: first states the core computation, then return values, then a heuristic note. No wasted words.

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

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

For a zero-parameter read-only tool, the description adequately covers purpose, output (rate, status, recommendations), and a caveat. Without output schema, it could detail output structure more, but complexity is low.

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; baseline score of 4 applies. The description correctly requires no input and does not need to compensate for schema coverage.

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

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

The description clearly states the tool computes the Storey Threshold (escalation rate) and returns current rate, status, and recommendations. The verb 'Compute' and resource 'Storey Threshold' are specific, distinguishing it from sibling tools.

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

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

No explicit guidance on when to use this tool vs. siblings. The heuristic note provides some context but not usage scenarios 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 already indicate read-only and idempotent. The description adds context on the output contents (chain verification, integrity hash) and reinforces the read-only nature, providing useful behavioral disclosure beyond annotations.

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

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

The description is concise at three sentences, front-loading the main purpose and then listing key output features. No redundant or vague statements.

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 adequately explains what is returned. Minor gaps include lack of pagination details or output size hints, but overall sufficient for a read-only export tool with good annotations.

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

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

All four parameters have schema descriptions (100% coverage), so the description adds little extra meaning. It summarizes the purpose of period_days and mai_level but does not enhance understanding beyond the schema.

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

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

The description clearly states the tool exports the forensic audit ledger as a compliance evidence package, specifying what it returns (chain verification, MAI breakdown, etc.). It is distinct from siblings like verify_ledger, which focus on verification rather than export.

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 compliance exports with 'Foundation for deliverable exports' and marks it as read-only. However, it does not explicitly contrast with siblings like verify_ledger or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns specific data fields (e.g., time saved, costs avoided), but does not disclose potential performance implications or data freshness.

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

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

Two concise sentences with no wasted words. The first sentence states purpose, the second lists outputs. Could be slightly more structured (e.g., separate purpose and outputs), but overall 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?

Description mentions output fields but lacks details on output structure, especially given nested input parameters and no output schema. The relationship between input (baselines) and output is not explained, leaving some 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?

Input schema covers 100% of parameters with descriptions. The description adds no additional meaning beyond the schema, as it only lists output fields, not parameter details. 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 a 'full economic + governance impact report' and specifies the returned pilot ROI data fields. This distinguishes it from the generic sibling 'generate_report' by focusing on impact and ROI.

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 like 'generate_report' or when not to use it. The description does not provide context for choosing this tool over siblings.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds detail on report contents (health, thresholds, compliance, metrics), providing behavioral context beyond annotations.

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

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

Two sentences, direct and front-loaded. No redundant information.

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

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

Given low complexity (1 param, no output schema), description adequately conveys purpose and key components. Could briefly mention return format, but not essential.

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

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

Schema coverage is 100% with a single parameter 'format' having enum and default. The description adds no extra meaning beyond the schema's 'Report format'.

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

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

The description clearly states the verb ('generate') and resource ('governance status report'), lists specific content categories, and distinguishes itself from the sibling 'generate_impact_report'.

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 like 'generate_impact_report' or when not to use it. Usage is only implied by the report content.

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 critical context: mandatory gate approval, what-you-approved-is-what-ran binding, preflight checks for hardening packs, and rejection of other pack types. Does not disclose on-failure behavior but sufficiently transparent.

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

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

Three concise sentences, each providing distinct value: purpose+gate, prerequisite+alternatives, preflight+classification. No waste.

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

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

Covers workflow context (dry-run binding, pack type restrictions, mandatory approval) and preflight checks, but does not describe return values or post-execution state. Acceptable given no output schema and destructive nature.

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

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

Schema has 100% parameter description coverage, so description adds minimal new param detail beyond reinforcing the inputs_hash binding. Adequate but not exceptional.

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 executes remediation or hardening packs, explicitly distinguishes from sibling tools like gia_run_patrol by rejecting patrol/audit packs, and ties to gia_dry_run_pack for input binding.

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

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

Provides explicit when-to-use (remediation/hardening packs with mandatory approval), when-not-to-use (patrol/audit packs with alternative), and prerequisite (inputsHash from dry run).

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, destructiveHint, idempotentHint. The description adds valuable context: it previews commands, compatibility, validation, blast radius, and returns a hash for binding, reinforcing its read-only, advisory nature.

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 efficiently convey the tool's output and classification. It is front-loaded with the core functionality. Slightly more structured formatting could improve, but it is concise.

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

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

Given no output schema, the description covers return values (inputsHash and preview details). It is sufficient for an agent to understand what the tool returns and how to use it. Minor missing details about 'hydrated commands' would not hinder usage.

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 has 100% description coverage for both parameters (pack_id and variable_overrides). The description does not add significant new 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 provides a preview of remediation pack execution, including hydrated commands, compatibility check, validation, and blast radius. It distinguishes itself from execution tools like gia_apply_pack.

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 applying a pack by noting it returns inputsHash for approval binding, and classifies itself as ADVISORY read-only. However, it does not explicitly state when not to use or name alternative 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?

Description details process: chunking, embedding, SHA-256 hashing, full audit trail, and classification as ADVISORY. This adds extensive behavioral context beyond annotations, which only indicate non-readonly, non-destructive, non-idempotent, non-open-world.

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

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

Three sentences front-loading purpose, then process details. No redundant information. 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?

Description covers ingestion process and audit trail well. Missing info on return value (no output schema) and behavior if roles/expectations fail. Still fairly complete for a tool with good annotations.

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

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

Schema covers 100% of parameters with descriptions. Description does not add new parameter-level semantics beyond stating default classification. No additional detail on parameter usage or constraints.

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

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

Description clearly states the tool's purpose: upload text content for governed retrieval with chunking, embedding, hash-verification, and audit trail. It uses specific verbs and distinguishes from siblings like gia_retrieve.

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

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

Description implies usage for governed document ingestion but does not explicitly state when to use or avoid this tool compared to alternatives. No guidance on scenarios 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 already provide readOnlyHint=true and destructiveHint=false, indicating safe operation. The description adds 'Classification: INFORMATIONAL', confirming non-destructive behavior but does not significantly extend beyond annotations.

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

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

Two compact sentences: first states the action, second lists filters. No unnecessary words, front-loaded with purpose.

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

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

The description is adequate for a simple listing tool but lacks detail about the return format (e.g., pagination, item structure). Since no output schema exists, more context could help, but the purpose is still clear.

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

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

Schema coverage is 100% with detailed enum descriptions for all 4 parameters. The description merely restates the filterable fields without adding new meaning, so baseline 3 applies.

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

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

The description states 'List available governed operations packs' with specific verb and resource, and lists filter criteria. It clearly distinguishes from sibling tools like gia_apply_pack (applies a pack) and gia_dry_run_pack (dry run).

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

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

The description implies usage for listing packs with available filters, but does not explicitly mention when not to use or provide direct comparisons to alternatives. However, sibling tool names make the context 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?

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description reveals hash verification, permission checks, TTL enforcement, audit logging, charter context enforcement with domain allow/denyLists, trust floor, classification floor, max chunks, and 'stricter-wins' rule for classification floors. No contradiction with annotations.

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

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

The description is well-structured with a strong lead sentence that summarizes the tool's core purpose. The following sentences add critical behavioral details without redundancy. It is slightly verbose but every sentence 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?

The description covers key governance features and parameter-specific behavior, which is sufficient given the lack of an output schema. It explains refusal logging and charter enforcement well, though it could briefly mention what the return format or error cases might look like.

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 for 'charter_id' and 'classification_floor' by explaining enforcement and 'stricter-wins' behavior. Other parameters like 'query' and 'domain' are sufficiently described in the schema, so the description does not need to add more.

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

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

The description clearly identifies the tool as a governed semantic search with hash verification, permission checks, TTL enforcement, and audit trail, distinguishing it from sibling tools by focusing on governance and charter enforcement. The classification 'ADVISORY — read-only search' further clarifies its non-destructive purpose.

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

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

The description explains when to use charter_id and classification_floor, and how they affect enforcement and refusal logging. However, it does not explicitly compare to sibling retrieval tools like 'gia_apply_pack' or 'gia_dry_run_pack', leaving the agent to infer usage boundaries.

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

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

The description aligns with annotations (readOnlyHint, destructiveHint, idempotentHint) and adds valuable behavioral details: read-only posture checks, rejection of remediation packs, deterministic pass/fail for audit packs per NIST controls with no AI interpretation. No contradictions found.

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?

Four sentences, efficiently structured. First sentence states core purpose and read-only nature, second covers classification, third rejects alternative packs and names right tool, fourth details audit behavior. Front-loaded with key action and resource.

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

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

Despite lacking an output schema, the description explains outputs (findings, compliance evidence, deterministic pass/fail) and conditional behavior when scout_data is omitted. Annotations provide additional safety context. The tool's role in a larger environment is clear, especially with sibling tool mentions.

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

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

All three parameters are described in the schema with 100% coverage. The description adds meaning: examples for pack_id, explanation of scout_data's dual role (if provided vs if absent returns command definitions), and condition for approved_by (required for high-sensitivity packs). This exceeds the basic schema descriptions.

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

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

The description clearly states the tool executes patrol or audit packs for read-only posture checks, producing findings or compliance evidence. It distinguishes itself from the sibling tool gia_apply_pack by explicitly rejecting remediation/hardening packs. The verb 'execute' and resource 'patrol or audit pack' are specific and unambiguous.

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

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

Guidelines are explicit: use for patrol/audit packs, not for remediation/hardening packs (which require gia_apply_pack). It also explains sensitivity-based classification (advisory vs mandatory) and when approved_by is needed. The description provides clear context for when to supply scout_data vs leaving it absent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context about output redaction ('Scout outputs are redacted'), which goes beyond annotations. 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?

Three sentences front-load the purpose and result, with no redundant information. 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?

The tool returns an EnvironmentProfile, but no output schema exists. The description mentions this return type, which is helpful. Additional structure detail would be beneficial but is not critical for a straightforward scan 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%; the schema already explains the optional scout_data parameter clearly. The description does not add new 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 specifies a specific verb ('run scout swarm') and resource ('target environment — OS, containers, services, network, storage'), clearly distinguishing it from sibling tools like gia_ingest_document or gia_run_patrol.

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 it is read-only and returns EnvironmentProfile, but does not explicitly indicate when to use this tool versus alternatives or provide exclusions. Contextual usage is implied but not explicit.

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

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

The description states that every request is 'recorded in the forensic ledger' (a write operation), contradicting the annotation readOnlyHint=true which declares the tool as read-only. This is a serious inconsistency.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value about the governance process 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?

Given the 8-parameter schema and no output schema, the description adequately explains the high-level workflow and governance constraints, though it omits specifics about return values or error handling.

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 schema already describes all parameters. The description adds no parameter-specific information beyond the schema, 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's function: requesting a governed LLM completion via MCP Sampling, distinguishing it from sibling tools by emphasizing the governance and client-mediated nature.

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

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

The description implies when to use (for governed sampling) but does not provide explicit when-not-to-use or alternatives; however, no alternative sampling tool exists among siblings, making the guidance adequate.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that results are grouped by tier and include descriptions, providing useful context beyond the annotations.

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

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

The description is a single, dense sentence that conveys all essential information with no wasted words.

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

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

With no parameters or output schema, the description fully explains what the tool returns (tool names grouped by tier with descriptions), which is sufficient for this simple list 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?

There are no parameters (0, 100% coverage). The description does not need to add parameter details; the baseline 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 clearly states the verb 'List', resource 'available tools', and adds specifics like 'at your current access tier' and 'grouped by tier with descriptions'. It distinctly separates this meta-tool from all 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?

The description implies when to use it (to check available tools for the current tier) but does not explicitly mention when not to use it or alternatives. However, given its unique purpose, this is clear 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?

Annotations are minimal (readOnlyHint=false, destructiveHint=false). The description adds that validations occur before loading, providing some behavioral context. However, it does not explain side effects (e.g., modifying agent context) or error handling on validation failure. 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, front-loaded with purpose, followed by validation details. No wasted words. Perfectly concise for the complexity.

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

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

The tool has 5 parameters and no output schema. The description covers purpose and validations but omits return value, error behavior, or usage context given many sibling tools. Adequate but not fully complete for an agent unfamiliar with the domain.

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 clear descriptions for each parameter. The description's mention of validating role access and context class aligns with operator_role and context_class, but does not add significant new detail beyond schema. Baseline 3 is appropriate given high coverage.

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

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

The description clearly states the verb 'load' and the resource 'Governed Memory Pack' into agent context. It also mentions validations, adding specificity. However, it does not explicitly differentiate from sibling tools like compose or promote, but the verb itself provides 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?

No explicit guidance on when to use this tool versus alternatives such as compose_memory_packs or promote_memory_pack. The description implies usage when needing to load a pack, but lacks when-not-to-use or prerequisite conditions.

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, destructiveHint, and idempotentHint, which the description does not contradict. The description adds behavioral context by stating the tool 'shows which controls are implemented,' clarifying the read-only mapping 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 two sentences: the first states the primary purpose, and the second adds specifics on scale. No unnecessary words; the structure efficiently conveys core information.

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

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

Given no output schema, the description explains the output shows which controls are implemented across frameworks. It does not detail the exact return format but is sufficient for a simple mapping tool with 1 parameter. The scale and scope are well communicated.

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

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

Schema coverage is 100% with a description for the framework parameter. The description lists the frameworks again but does not add new meaning beyond the schema. It briefly mentions the output (63 controls) which gives context but not specific parameter guidance.

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 maps GIA governance components to 10 named compliance frameworks and mentions 63 controls. The verb 'Map' and specific resource (regulatory frameworks) make the purpose unambiguous, and it distinguishes itself from sibling tools like 'assess_risk_tier'.

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

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

The description implies use for compliance mapping but provides no guidance on when to use this tool over alternatives (e.g., when a specific framework is needed vs. all). No explicit when-not or exclusion criteria are given, which is a moderate gap given the many 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?

Annotations already mark it as read-only, non-destructive, and idempotent. The description adds behavioral context by specifying the tool returns supervisor state, repair history, and failure counts, and clarifies the scope is all governed AI agents. 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 sentence that conveys purpose and return data efficiently. It is front-loaded with the verb 'Monitor' and resource 'status and health of all governed AI agents.' No redundant or irrelevant 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 simplicity (0 parameters, no output schema), the description is complete: it specifies what it monitors, the scope, and what data it returns. Annotations cover safety. No gaps.

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

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

The input schema has no parameters (0), so the description is not required to explain them. It adds value by describing the return payload, which compensates for the lack of an output schema.

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

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

The description clearly states it monitors status and health of all governed AI agents, listing specific return data (supervisor state, repair history, failure counts). The title 'Monitor Agent Health' reinforces the purpose. Among siblings like agent_citizenship_status or colony_health, this tool is clearly distinguishable as a general health check for all governed agents.

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 general monitoring of governed agents but provides no explicit guidance on when to use this tool versus alternatives like colony_health or srt_diagnose. It lacks exclusion criteria or a when-not-to-use note.

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?

Adding to annotations, the description clarifies scope (includes snapshot, chain, intelligence, compliance) and reaffirms read-only nature. This context goes beyond the annotations' boolean hints by specifying what aspects are assessed.

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

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

Two concise sentences; front-loaded with the core purpose, then lists assessed areas. No wasted words.

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

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

Given no output schema, the description gives a solid overview of what is assessed. However, it does not specify the format or structure of the output (e.g., JSON, pass/fail), which could be helpful for an agent parsing results. Slightly incomplete but still adequate.

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

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

No parameters exist (schema coverage 100%), so the baseline of 4 applies. The description doesn't need to add parameter details beyond the schema.

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

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

The description uses a specific verb ('Assess') and resource ('Phoenix recovery readiness'), and lists key components (snapshot availability, chain integrity, etc.). It clearly distinguishes from sibling tools by focusing on overall readiness rather than individual checks like phoenix_snapshot.

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

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

Explicitly states 'Classification: INFORMATIONAL — read-only assessment', which guides when to use (safe, non-destructive info). No explicit alternatives or when-not-to-use, but the classification implies suitable for informational queries without side effects.

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 claims the tool is read-only with no mutations, but annotation readOnlyHint is false, creating a direct contradiction. The description does add context about SHA-256 hashing and chaining, but the contradiction overrides.

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 plus a classification line, front-loaded with purpose, no redundant information.

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

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

No output schema, so description should hint at return value; it mentions chaining but not that a snapshot ID is returned. Still, sufficiently complete for a state capture tool with annotations covering mutation safety.

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 does not add meaning beyond the schema's property descriptions; 'trigger_type' and 'notes' are already documented.

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 creates a governed state snapshot and enumerates the captured elements (ledger, gates, contracts, etc.), distinguishing it from sibling tools like phoenix_recovery_health or phoenix_verify_integrity.

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 capturing platform state but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.

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

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

Annotations already indicate read-only and non-destructive. The description adds specific behavioral context: checks ledger, agents, thresholds, intelligence continuity, and returns a report with compliance mapping. 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?

Two sentences: first states action and scope, second states output and classification. Front-loaded, no wasted words, immediately informative.

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 adequately describes return ('comprehensive integrity report with compliance mapping') and lists checks. Slightly vague but sufficient for a verification tool with no parameters.

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 has zero parameters, so no parameter documentation needed. The baseline of 4 applies as the description doesn't need to add parameter details.

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: 'Verify the integrity of GIA governed operations' with specific checks (ledger, agents, threshold, intelligence continuity). It distinguishes from siblings like 'verify_ledger' by covering multiple dimensions.

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

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

The description implies use for comprehensive integrity checks but lacks explicit guidance on when to use this tool over alternatives like 'verify_ledger' or 'system_status'. No when-not-to-use or alternative references.

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 annotations by explaining that this tool promotes distilled EPHEMERAL packs and requires a mandatory gate. The annotations already include destructiveHint=true, and the description complements this with the promotion process detail, though it could further clarify specific 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 very concise at two sentences, front-loading the core purpose and then adding essential process context. No redundant information.

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

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

Given the complexity (no output schema, destructive hint), the description explains the outcome (EPHEMERAL to CASE/ORG) and the gate requirement. However, it could be more complete by noting irreversibility or other consequences, but the sibling context (distill_memory_pack) helps fill some 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?

All 4 parameters are fully described in the input schema (100% coverage), so the description does not add significant extra meaning. The description mentions 'after human review' which relates to approval parameters, but does not provide additional details 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 promotes memory packs to a higher trust level after human review, specifying the transition from EPHEMERAL to CASE or ORG. It uses a specific verb and resource, and distinguishes itself from sibling tools like 'distill_memory_pack' and 'compose_memory_packs'.

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

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

The description mentions 'Requires MANDATORY gate' and implies usage after human review, but does not explicitly state when to use versus alternatives or when not to use. No exclusions or alternative tool names are provided.

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

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

Annotations already indicate non-read-only, non-destructive, non-idempotent. The description adds context about event types but does not disclose additional behaviors such as side effects, authentication requirements, or rate limits.

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 (20 words) that is front-loaded and contains no wasted words.

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

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

For a simple logging tool with two parameters and no output schema, the description adequately conveys purpose and event types. It lacks mention of error conditions or return behavior, but these are minor.

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

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

Schema coverage is 100% and already describes parameters. The description lists event types in natural language, adding context but not essential beyond the schema.

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

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

The description clearly states the verb 'Record' and resource 'governance event', and provides specific examples of event types (gates triggered, drift prevented, etc.), distinguishing it from sibling tools like 'record_value_metric'.

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

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

The description implies usage through examples of event types but does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, consistent with the description. The description adds context that the tool records multiple metrics, but does not disclose idempotency, error handling, or response behavior beyond what annotations provide.

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 immediately states the purpose, followed by specific metrics. It is concise 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?

Given the tool's complexity (9 parameters, 6 required) and absence of an output schema, the description adequately conveys the purpose and scope. However, it could briefly note the expected return outcome (e.g., success indicator) for full 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 description coverage is 100%, so the description adds no significant meaning beyond the schema. The high-level mention of tracked metrics aligns with parameters but does not provide additional context for parameter values or usage.

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

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

The description clearly identifies the action ('Record a workflow value metric') and the specific metrics tracked (time saved, risk blocked, success rate, autonomy level, task complexity), distinguishing it from sibling tools like 'record_governance_event' which focus on governance rather than value measurement.

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 'record_governance_event' or other recording tools. The description implies it is for ROI reporting but does not specify exclusivity or prerequisites.

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

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

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds detailed behavioral traits: retrieval is role-bound, tenant-bound, hash-verified, and ledgered. It also states that GIA decides what to serve, implying non-deterministic or filtered results. No contradiction with annotations; the description enriches the behavioral context significantly.

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

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

The description is three sentences, each adding value: first states purpose, second explains governance, third reinforces the principle. It is front-loaded with the core function and avoids redundant phrases. There is no wasted text, making it highly concise for a tool with 10 parameters.

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

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

The tool has 10 parameters and no output schema. The description explains the governance and security aspects but does not indicate the return format (e.g., structure of retrieved context). For example, it doesn't specify whether multiple documents are returned or if there is pagination. This gap in output behavior, along with lack of differentiation from similar siblings like 'gia_retrieve', makes it only moderately 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%, so baseline is 3. The description does not add specific parameter-level details beyond what is already in the input schema. While it mentions 'declare intent' which aligns with the 'query' and 'context_class' parameters, it does not elaborate on the meaning or interaction of parameters, thus staying at baseline.

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

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

The description clearly states the tool requests governed internal context (policies, SOPs, architecture docs, compliance rules, playbooks). It uses a specific verb 'Request' and identifies the resource as 'governed internal context'. Sibling tools like 'gia_retrieve' or 'agent_rights' have different scopes, and this description distinguishes the tool as the one for requesting context under contract.

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 on when to use: agents declare intent, GIA decides, and retrieval is role-bound and tenant-bound. It implies that agents should not directly access internal data but request it under contract. However, it does not explicitly mention alternatives or when not to use, missing the strictest criteria for a 5.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the key behavioral trait that it is caller-assessed, meaning the tool does not independently verify inputs. This goes beyond annotations and provides important context for safe usage.

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

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

Two dense sentences with no redundancy. First sentence defines purpose and inputs. Second sentence describes output and clarifies the tool's role. Every word earns its place, making it highly efficient for an agent to parse.

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

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

Given no output schema, the description sufficiently explains return values (weighted composite and pass/fail). Parameters are well-covered. The tool's moderate complexity is fully addressed, and the clarification about caller-assessment ensures the agent understands the tool's limitations.

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 value by summarizing the purpose of the parameters ('Integrity, Accuracy, and Compliance values (0-1)') and stating the output ('Returns weighted composite and pass/fail'). This unifies the parameter meaning beyond individual schema entries.

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 computes a weighted governance score from three caller-provided values (Integrity, Accuracy, Compliance) and returns a weighted composite and pass/fail. It uses specific verbs 'compute' and 'returns', and distinguishes itself from independent evaluation 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 explicitly says scores are caller-assessed and the tool applies weights/thresholds, not independent evaluation. This guides when to use it (when you have self-assessed scores) and when not (if you need independent evaluation). However, it does not name specific alternative siblings, which would improve clarity.

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 some context beyond annotations: it notes that the pack becomes immutable and TTL-bound, and mentions trust level enforcement. However, it does not detail behaviors like idempotency, side effects (e.g., overwriting existing packs), or failure modes. Annotations already indicate it is not read-only or destructive, so 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 of 24 words, efficiently conveying the core purpose and key attributes. It is front-loaded with the action and resource. However, it could benefit from a slight breakdown of concepts for clarity.

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

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

Given the tool has 15 parameters (11 required) and no output schema, the description is too brief. It does not explain what happens after sealing (e.g., how to retrieve or use the pack), prerequisites for roles (sealer_role), or implications of trust level enforcement. The complex domain and sibling tools require more context for correct invocation.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description does not add per-parameter meaning beyond mentioning 'TTL-bound' (ttl_hours) and 'trust level enforcement' (trust_level, sealer_role). It does not compensate for any gaps, so baseline of 3 is appropriate.

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

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

The description clearly states the action 'Create and hash-seal' and the resource 'Governed Memory Pack (GMP)', and mentions key properties like immutable, TTL-bound, and trust level enforcement. It implicitly distinguishes from siblings like compose_memory_packs or load_memory_pack by focusing on creation, 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?

No guidance on when to use this tool versus alternatives such as compose_memory_packs or distill_memory_pack. The description does not provide any when-to-use or when-not-to-use context, leaving the agent to infer from the tool 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 set destructiveHint=true, indicating mutation. The description adds critical behavioral context: it is a human-in-the-loop gate and plans cannot execute without approval. 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?

Extremely concise: three sentences pack the purpose, mandatory classification, and action parameter usage with example values. No wasted words.

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

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

Given the annotations and schema, the description covers the essential behavioral aspects (mandatory, human gate, action values). Lacks explicit mention of return value or post-approval effects, but the tool's role as a gate is sufficiently clear.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds minor clarification on action usage and the conditional requirement for reason on rejection, which the schema notes but does not enforce as required. This adds some value beyond the schema.

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

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

The description clearly states 'Approve or reject a pending SRT repair plan,' which is a specific verb+resource. It distinguishes this tool from sibling tools like srt_diagnose and srt_run_watchdog by focusing on the approval 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?

Explicitly states 'Classification: MANDATORY' and 'Repair plans CANNOT execute without explicit human approval,' providing clear context for when to use. However, no explicit when-not-to-use or alternatives are mentioned, but the mandatory nature implies it's the only approval step.

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 claims 'read-only analysis, no mutations', but the annotation readOnlyHint is false. This is a direct contradiction. Additionally, the description does not disclose other behavioral traits such as authentication needs, rate limits, or side effects beyond the contradictory read-only claim.

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

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

The description is concise with three sentences. The first sentence states the action and resource, the second explains the outputs, and the third clarifies the classification. Every sentence adds value without redundancy. Ideal length and structure.

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

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

The description covers the purpose and outputs but lacks details on the return format or structure. Since there is no output schema, some description of what the repair plan looks like would be helpful. However, the tool is relatively simple and the description provides adequate context for an agent to understand the behavior.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds context about the diagnostic process but does not provide additional semantics for the parameters beyond what the schema already offers. Baseline 3 is appropriate for high coverage.

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

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

The description clearly states the verb 'run', the specific tool 'SRT Diagnostician', and the resource 'incident'. It lists concrete outputs: matching to playbooks, root cause identification, and repair plan. It also distinguishes itself by explicitly classifying as 'ADVISORY — read-only analysis, no mutations', which differentiates it from sibling tools like srt_approve_repair or srt_generate_postmortem.

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 diagnosing an incident but does not provide explicit guidance on when to use this tool versus alternatives. For example, it does not contrast with srt_run_watchdog or other diagnostic-related tools. The context is clear but lacks exclusions or alternative recommendations.

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 are present (readOnlyHint=false, destructiveHint=false, idempotentHint=false) but are generic. The description clarifies the output structure and that the classification is advisory, adding behavioral context. However, it does not disclose side effects (though likely none) or specify whether repeated calls produce the same report. The description complements annotations adequately.

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-loading the core purpose. Every piece of information (timeline, root cause, metrics, playbook delta) is valuable and succinct. No redundant or unnecessary text.

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

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

Given the single parameter and no output schema, the description covers the tool's purpose and output structure well. It lists all major sections of the report. However, it does not mention the output format (e.g., text, file, JSON) or any potential side effects (though none are expected). Slightly more detail on return value would raise completeness to 5.

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 one parameter 'incident_id' with full description coverage (100%). The tool description repeats the schema description without adding extra meaning, so no value added beyond schema. Baseline score of 3 applies.

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

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

The description clearly states the verb 'Generate' and the resource 'structured postmortem report for a completed SRT incident'. It lists specific contents (timeline, root cause, etc.) and ends with classification 'ADVISORY', making it distinct from siblings like srt_diagnose or srt_approve_repair.

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

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

The description specifies 'for a completed SRT incident', implying it should be used only after an incident is resolved. However, it does not explicitly state when not to use it, nor does it mention alternative tools for ongoing incidents (e.g., srt_diagnose) or other conditions. This leaves some ambiguity for the agent.

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 claims 'read-only, no side effects' but annotations set readOnlyHint=false, a direct contradiction. This significantly impairs agent understanding of the tool's safety. No further behavioral context is provided beyond the contradictory classification.

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-loading the purpose and listing the probe types. It is efficient and contains 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?

The description lacks details about return values (no output schema) and does not cover potential behaviors like timeouts or error handling. Given the tool's complexity, this leaves gaps for agent invocation, though the input schema partially compensates.

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

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

The sole parameter 'check_results' is clearly documented as ignored and kept for backward compatibility. The description adds essential context that the schema alone does not convey, achieving full parameter clarity despite the parameter being vestigial.

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 specifies the tool runs real health check probes (API, frontend, disk, memory, TLS, DB, DNS) and returns measured values. It distinguishes itself from sibling tools by focusing on actual probe execution without AI-provided data.

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