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

Annotations already indicate read-only and non-destructive behavior. The description aligns with this (compute) and adds no extra context about auth, rate limits, or side effects, so it is neutral rather than additive.

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 moderately concise, front-loaded with the core purpose, and uses a clear list of actions with parenthetical explanations. It conveys substantial detail without excessive verbosity, though it is slightly longer than necessary.

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

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

The description gives a good idea of what each action returns (e.g., overview, chart, metrics) but does not specify the exact output structure or format. Since there is no output schema, the description adequately informs the agent of expected results.

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

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

The schema covers all parameters with descriptions, but the tool description adds value by mapping specific parameters to actions (e.g., days for burndown, window_days for velocity, milestone_id for critical_path). This enhances understanding beyond the 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 the tool computes various analytics metrics and lists supported actions like summary, velocity, burndown, etc. It is specific and distinguishable from sibling tools like query_graph or get_events by focusing on derived metrics rather than raw data.

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 lists supported actions but does not explicitly state when to prefer this tool over alternatives. It implies usage for analytics but lacks direct comparison or conditional guidance (e.g., 'use this for high-level metrics; use query_graph for raw data').

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 behavioral context beyond the annotations by mentioning 'append-only' and listing three distinct actions (log, changelog, post_mortem). However, it lacks details on side effects, error handling, or output format. The annotations already cover read-only and non-destructive nature, which the description does not contradict.

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

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

The description is concise and well-structured: two sentences with a clear overall purpose followed by a list of supported actions. It avoids redundancy and is easy to parse.

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

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

There is no output schema, and the description does not explain what log or changelog return. It only hints that post_mortem produces a 'structured markdown report'. It also omits details about pagination or result types, leaving significant gaps for the agent.

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

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

The input schema already provides descriptions for all parameters, so the baseline is high (coverage 100%). The description does not add meaningful clarifications about parameter usage, such as which parameters apply to which action. It repeats the parameter list implicitly but without extra semantic value.

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

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

The description clearly states the tool's purpose: inspecting an append-only event audit ledger, querying structured changesets, and generating session post-mortems. It also lists three specific actions (log, changelog, post_mortem) which distinguish it from siblings like query_graph or get_analytics.

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 over alternatives. It lists actions but does not explain under what circumstances each should be invoked, nor does it differentiate from other query/analytics tools. Users must infer usage from the actions.

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

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

Annotations indicate the tool is not read-only (readOnlyHint false) and not destructive by default, but the description explicitly lists import and export actions, which are non-destructive but involve changes. The description adds context about supported formats and actions (e.g., export to JSON/DOT/Mermaid) that helps set expectations. It does not disclose behaviors like overwrite behavior beyond the 'force' parameter, but annotations already cover none of that, so the description's additional action list adds 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 long single sentence that enumerates nine actions with parenthetical details. It front-loads the general purpose but becomes cluttered. It could be structured as a list for clarity. It is not concise given the number of actions covered.

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

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

Given the complexity of a 13-parameter, multi-action tool, the description is too thin. It does not specify which parameters are required or optional for each action, nor does it provide any action-specific parameter requirements or output formats. With no output schema and zero required parameters, an agent cannot reliably infer which parameters to supply for a given action. The description covers the action names but not the full usage context.

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

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

Schema coverage is 100%, so all 13 parameters are described in the schema. The description lists actions and mentions some associated parameters (e.g., for import_graph: nodes, edges) but doesn't go beyond the schema's own descriptions. The description helps map which parameters apply to which actions, but this mapping is implicit rather than explicit, so it doesn't fully compensate for the lack of action-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 lists a clear set of actions (export_graph, import_graph, etc.) across multiple domains (graph, issues, trajectories, metrics), which makes the tool's scope evident. However, it packs many operations into one tool, so it does not differentiate itself from siblings like manage_nodes or manage_specs, which likely handle more focused operations.

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

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

The description enumerates actions but gives no guidance on when to choose this tool over siblings. For instance, it doesn't explain that manage_nodes should be used for fine-grained node edits while import_graph is for bulk loading. There are no explicit when-to-use or when-not-to-use 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?

The description explicitly notes that restore is destructive and that the force parameter allows overwriting during restore or merge, which is valuable behavioral information. However, the annotation destructiveHint=false directly contradicts this, as the tool can perform destructive operations. This is a critical inconsistency, and the description fails to align with the structured metadata, warranting a score of 1.

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 but effectively packs information: it states the general purpose and then lists all six actions with brief parenthetical clarifications. It is concise and front-loaded, though the dense list could be more readable with bullet formatting. Every phrase adds information without 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?

With no output schema and a tool that includes destructive actions, the description should explain behavior in more depth—such as where backups are written, prerequisites for restore, how merge resolves conflicts, and what the audit reports. It only names actions without detailing side effects, expected returns, or edge cases, leaving substantial gaps for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by enumerating the valid values for the action parameter (backup, restore, audit, merge, branch_diff, branch_merge), which the schema leaves vague as 'the database administration or VCS sync action to execute.' For other parameters, the schema descriptions suffice, but the action list is a notable contribution.

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 defines the tool as handling SQLite database maintenance, backups, integrity checks, and Git VCS sync, and it lists six specific actions. This distinguishes it from sibling tools like manage_nodes or manage_sessions, which focus on other resources. However, it is a multi-action tool, so the purpose is broad rather than a single verb, preventing a perfect score.

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 contexts—database maintenance and VCS state sync—but does not explicitly compare to alternatives or state when not to use it. While the tool name and action list make its domain clear, there is no direct contrast with sibling tools or exclusion criteria, so guidance is only implied, not explicitly provided.

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

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

The description adds value beyond the annotations by disclosing the action enum ('add', 'remove', 'batch_add', 'link_visual') and clarifying that 'batch_add' is atomic ('create multiple relationships atomically'). The mention of 'link_visual' provides context for what would otherwise be an opaque parameter. However, there's no mention of destructive-behavior details, permission requirements, or failure semantics. The atomicity note shows the author knows how to disclose behavior when they want to.

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

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

The description is compact—two sentences—but the parameter list in parentheses is dense and could be structured more effectively. The atomicity callout is front-loaded appropriately. It's readable but not as scannable as the best examples.

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 mutating, multi-action tool with no annotations, no output schema, and 12 parameters, a description would need to explain parameter groupings (which params apply to add vs. batch_add vs. link_visual) and clarify the new semantics of the 'link_visual' feature. The current description names the actions and parameters but doesn't provide this mapping. However, the schema covers all parameters, and the basic graph-operation behavior is simple enough for an agent to infer.

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

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

With schema description coverage at 100%, the schema documents all 12 parameters, including the enum for 'type' and descriptions for each field. The description meaningfully adds value by naming the four actions and clarifying the atomicity of batch_add. However, the description could have provided a mapping between parameters and actions, which is essential given the complexity of a multi-action tool.

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

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

The description uses a specific verb ('Manage'), a clear resource ('typed graph relationships between nodes'), and enumerates supported actions (add, remove, batch_add, link_visual). However, it doesn't differentiate this tool from its siblings beyond the generic graph-relationship scope, and 'Manage Edges' is tautological with the tool name. It's functional but lacks the precision of the best examples.

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 a complex tool with a 'link_visual' action that 'links task or artifact to visual memory state,' which is somewhat distinct from the first three actions. However, it doesn't state when to use this tool vs. alternatives like manage_nodes, manage_tasks, or manage_snapshots, nor does it address the parameter-grouping complexity (12 params, 0 required) or which parameters apply to which action. The usage context is only partially clear.

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

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

The description adds useful behavioral detail beyond annotations: 'remove (delete node and cascade edges)' discloses destructive cascading, 'batch_create/batch_update atomically' discloses atomicity, and 'add_note (log observation node with optional context link)' discloses side effects. However, the disclosed cascade-delete behavior directly conflicts with annotations' destructiveHint=false, creating trust ambiguity about whether remove is safe.

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

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

Every word earns its place — no filler. But the entire action taxonomy is crammed into one run-on sentence, making it hard to scan for a specific action. A bulleted or structured enumeration would materially improve parseability without adding length.

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

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

This is a complex dispatcher (21 params, 9 actions, nested objects) with no output schema, yet the description leaves critical gaps: no action-to-parameter mapping, no return-value or response-shape disclosure for each action, and no per-action constraints. An agent cannot reliably determine which parameters are relevant for a chosen action or what result to expect, so the definition is incomplete for its complexity.

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

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

Schema coverage is 100%, so all 21 parameters carry descriptions in the schema; the tool description itself adds no parameter details beyond the action names. The description does not map actions to their relevant parameters (e.g., that 'algorithm' applies only to 'search'), but per the baseline rule for full schema coverage, the description need not duplicate the schema. The un-enumerated 'action' string benefits slightly from the listed valid values.

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

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

The description states 'Manage graph nodes in the state graph' with a specific resource, and enumerates nine concrete actions (create, update, get, remove, list, search, batch_create, batch_update, add_note). This distinguishes it from siblings like manage_edges and manage_snapshots by resource. However, 'manage' plus a long action list is a dispatcher-style breadth that weakens the single-purpose clarity.

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

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

No when-to-use or when-not-to-use guidance is provided. The sibling list includes conceptually overlapping tools (manage_tasks, manage_specs, query_graph, manage_edges), and the description never explains when to call manage_nodes versus those alternatives, nor does it note that 'task'/'spec' node types exist here despite dedicated manage_tasks/manage_specs siblings. An agent has no routing cues.

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=false (mutation) and destructiveHint=false (not destructive). The description adds the notion of sensitive actions like 'start' and 'end' but does not disclose side effects, reversibility, or what happens to session data on end. It introduces 'context snapshot' and 'next tasks' for bootstrap, which is a helpful behavioral detail, but lacks depth about state changes or consequences.

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 compact sentences with zero filler. The purpose is front-loaded, and the action list is provided efficiently in parentheses. Every word earns its place, making it easy to scan.

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 8 parameters, multiple actions, and no output schema, the description is under-specified. It does not explain which parameters apply to which action (e.g., session_id for end, limit for list), nor does it describe the return shape or outcomes. The absence of output schema amplifies the gap, leaving an agent without enough context to call the tool correctly across different actions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond the schema; it only lists action names without mapping them to required parameters. An agent must rely solely on the schema to know which fields matter for each action, which the description does not clarify.

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

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

The description clearly states a specific verb + resource: 'Manage agent tracking sessions and multi-turn workflow attribution.' It also enumerates four concrete actions (start, end, list, bootstrap), which differentiates it from sibling tools like manage_nodes or manage_tasks. An agent can immediately understand the tool's role without opening the schema.

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

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

The description implies usage by stating its purpose and actions, but does not explicitly say when to use this tool versus alternatives. No exclusions or comparisons are provided. For example, it doesn't mention that tasks would be managed elsewhere, or when a session must be started before tracking. The guidance is implicit rather than explicit.

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

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

The annotations indicate destructiveHint=false, yet the description includes 'revert' and 'undo' actions which are destructive operations. This is a clear contradiction. Additionally, the description does not disclose side effects like state mutation, permission requirements, or irreversible changes, so behavioral transparency is severely lacking.

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, a single sentence that enumerates the supported actions. It is well-structured and front-loaded with the overall purpose, making it easy to scan and understand.

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 crucial context: it does not mention what each action returns, whether results are paginated, error handling, or examples. Since there is no output schema, the description should clarify expected outputs but does not. It also lacks notes on side effects or limitations, leaving an agent with incomplete information for invoking the tool correctly.

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

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

The schema descriptions cover all 9 parameters, but the tool description itself does not elaborate on parameter usage. It does list the action values in the text, which partially clarifies the action parameter, but it does not map parameters to specific actions or explain how they interact. The description adds some value by naming the actions, but parameter semantics are mostly derived from the schema.

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

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

The description clearly states the tool manages snapshots and lists the specific actions (save, list, diff, get_state, revert, undo, get_history). This distinguishes it from sibling tools like manage_nodes or query_graph, so an agent can identify its purpose readily.

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

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

The description provides no guidance on when to use this tool vs alternatives. It does not mention conditions like 'when you need to save or revert state' or reference scenarios that would make this tool preferable to others. The action list is informative but lacks situational 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 only carry readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description must carry the behavioral weight. It does: scaffold generates, ingest parses into graph nodes, verify marks criteria, decompose creates plan/milestones/subtasks. These are honest descriptions of mutating behaviors. It does not disclose deeper effects like undo behavior or permissions, but that is not critical here.

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 first sentence states the broad purpose, and the second packs all seven actions into a compact, scannable list. Every phrase adds information; there is no repetition, filler, or restating of the tool name. This is an efficient structure for a multi-action dispatcher.

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

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

Given 13 parameters, 7 actions, no output schema, and no required parameters, the description is strong on action semantics but weak on action-to-parameter mapping. An agent might struggle to know, for example, which parameters to pass for 'compliance' or whether 'template' requires both 'template' and 'name'. This is the main completeness gap.

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

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

Schema description coverage is 100%, so the schema itself documents all 13 parameters. The description adds semantics to the action enumeration values (e.g., what 'scaffold' means) but does not map which parameters each action requires. Baseline 3 is appropriate because the schema handles the parameter-level burden.

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

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

The description opens with a clear domain ('Spec-Driven Development (SDD) lifecycle and workflow template generation') and then enumerates seven concrete actions with brief parenthetical effects. This distinguishes manage_specs from sibling graph-management tools like manage_nodes and manage_edges by scope and action set.

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 action list establishes clear context for when to use this tool (when performing SDD scaffold/ingest/export/compliance/verify/decompose/template operations). It does not explicitly name sibling alternatives or state exclusions, but the use cases are self-evident from the action names and descriptions.

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, openWorldHint=false, destructiveHint=false, matching the description's implied mutation operations like 'complete' and 'auto_prune'. The description adds context by detailing what each action does (e.g., 'cancel stale in-progress tasks'), but it doesn't disclose side effects beyond action names, such as reversibility, permission requirements, or rate limits. It does not contradict annotations, and given the annotation coverage, the description is adequate but not rich.

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

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

The description is a single dense paragraph that starts with a clear general statement, then lists each action with a short parenthetical explanation. It's front-loaded and free of fluff, though the long enumeration could be more scannable with line breaks. Still, it is appropriately sized for the tool's scope.

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 (20 params, no required, no output schema), the description provides a high-level overview of actions but lacks a mapping from actions to parameters. An agent may struggle to know which parameters apply to each action (e.g., task_id for complete, query for find_similar_blockers). While the schema documents each parameter individually, the description doesn't synthesize this information. The description is adequate for initial selection but insufficient for correct invocation without further inference.

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

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

The schema provides descriptions for all 20 parameters (100% coverage), so the baseline is 3. The description does not add any parameter-specific details; it mentions actions but doesn't map them to parameters. However, since the schema already covers semantics, the description doesn't need to compensate. It offers no extra benefit beyond what the schema provides.

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

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

The description clearly states the tool's purpose: task management via multiple specific actions (next, complete, find_blocked, etc.), each with a brief explanation. The resource (tasks) is explicit and distinct from sibling tools like manage_nodes or manage_snapshots, though it doesn't explicitly contrast them. The listing of actions is informative and covers the main capabilities.

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

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

The description provides no guidance on when to use this tool versus alternatives. It simply enumerates supported actions without mentioning circumstances where a sibling tool would be more appropriate, nor does it state any prerequisites or exclusions. An agent must infer from the tool name that it's for tasks, but there's no explicit routing to help select this over manage_nodes or manage_snapshots.

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

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

The annotations already declare readOnlyHint and destructiveHint, and the description reinforces the 'safe read-only' nature. It also mentions cycle detection for trace, which adds behavioral detail beyond the annotations. However, it does not describe return formats or potential side effects (though read-only implies none).

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

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

The description is concise and lists actions clearly, but it is a single sentence that packs many details. It front-loads the purpose and then itemizes actions, which is efficient, though the lack of separate sections might reduce scannability.

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 main actions and parameters reasonably well for a read-only query tool. However, it does not explain when to use specific actions (e.g., subgraph vs trace vs raw) or how they relate to sibling tools. No output schema exists, so return values are not described, which is acceptable per guidelines.

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

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

The schema covers 100% of parameters with descriptions, but many descriptions are minimal (e.g., 'Query parameters for raw action'). The description provides little additional semantic meaning beyond the schema, and the action parameter's possible values are only listed in the description, not in the schema.

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

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

The description clearly states the tool queries graph topology, neighborhoods, dependency paths, and safe read-only SQL queries, listing specific actions. It names the resource (graph) and the verb (query), but does not explicitly differentiate from sibling tools beyond the read-only 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 implies usage for graph-related queries and read-only operations, but does not explicitly state when to use this tool versus alternatives like manage_nodes or get_analytics. No exclusions or alternatives are mentioned, though the read-only nature is implied.

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

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

Annotations declare destructiveHint=false despite actions like prune_events, compact, archive, and dedupe being potentially destructive. The description notes prune_events requires admin mode and provides a dry_run parameter for simulation, and dedupe uses apply for merging, but it doesn't explicitly clarify that these actions alter state. The description partially compensates by warning about permanent pruning, but it doesn't fully address the contradiction with the destructive hint.

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 long single sentence listing many actions and parameters, which becomes dense. It is front-loaded with the main purpose but the long list of actions feels like a wall of text. It could be more structured (e.g., grouping actions by type: health checks vs maintenance) to improve scannability.

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 10 params, no required params, and no output schema, the description covers the actions and key params but does not explain return values or what constitutes a successful execution. It lacks clarity on how the agent knows which action to choose for a given need, and doesn't explain the relationship between actions like check_refs and auto-heal or older_than vs older_than_days. There is also no mention of error conditions or side effects beyond prune_events admin requirement.

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 all parameters have descriptions. The tool description adds context by explaining which action each parameter relates to (e.g., dry_run for prune_events, older_than for prune_events, apply for dedupe, auto_heal for check_refs). This mapping helps the agent use parameters correctly, adding 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's purpose: running graph diagnostics and maintenance, listing specific actions. It distinguishes from siblings like manage_nodes, manage_edges, manage_database, and get_analytics by covering a broad set of checks and maintenance actions. However, it doesn't explicitly differentiate from manage_database which may overlap with storage maintenance actions (compact, archive, prune).

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 lists supported actions and explains some parameters (e.g., admin mode for prune_events, auto-heal for check_refs), but does not provide explicit guidance on when to use this tool versus the many siblings (manage_nodes, manage_edges, manage_database, get_analytics). The list of actions implies usage but doesn't state exactly when this tool is the right choice over 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 the operation is not read-only and not destructive, while the description adds meaningful behavioral detail: notices are ephemeral, expire via TTL, and reads only return active non-expired notices. It does not cover overwrite, visibility, or authentication, but it goes beyond the annotations without contradicting them.

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

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

Two sentences with no filler: the first front-loads the purpose and the second summarizes the supported actions. It earns its place without repeating the schema.

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

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

For a 7-parameter tool with no output schema and minimal annotations, the description conveys the core blackboard concept but leaves the per-action call shape (which parameters apply to post vs read) and the read return behavior to inference. The generic schema descriptions make this a noticeable gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds extra meaning by defining the legal action values ('post' and 'read') and explaining how topic, content, and ttl_seconds factor into a post. It does not clarify project, agent_id, or agent_role beyond their 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 names a specific resource (shared blackboard), a clear purpose (asynchronous agent coordination), and the supported actions (post and read). It distinguishes itself from the manage_*/query_* sibling tools rather than merely restating its title.

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

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

It provides a clear intended usage context: asynchronous agent coordination via a shared blackboard. It does not explicitly name alternatives or when-not-to-use cases, but the purpose is obvious enough for an agent to select it appropriately.

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