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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds useful value by listing the shape of returned artifacts (dashboard, velocity charts, burndown series, DAG, reports) despite no output schema existing, though it does not disclose per-action behavior nuances.

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 routing rule is well front-loaded, but the eleven-action list is repeated twice within the description itself and again in the schema, which is redundant. It is somewhat over-sized for the information conveyed.

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, the description usefully summarizes the return values, and annotations cover the safety contract. It is close to complete for a multi-action tool, missing only action-level guidance about which parameters apply to which action.

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

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

Schema description coverage is 100% and the enum plus per-parameter descriptions fully document the inputs, so the schema carries the burden. The description restates the action list but adds no syntax, defaults, or format detail beyond what the schema already provides.

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

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

The description gives a specific verb+resource ('Compute workflow metrics') and enumerates the concrete analytics it produces, so an agent knows exactly what this tool does. It also explicitly distinguishes itself from the similarly-named sibling query_graph.

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 names the alternative (query_graph) and the conditions that select this tool (high-level progress statistics, ROI metrics, decision-conflict auditing). However, the routing guidance only covers the metrics/high-level cases and does not explain when to pick the decision-analysis actions (decision_trail, find_related_decisions, context_snapshot) over other 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value by characterizing the ledger as 'append-only' (immutability of the underlying data) and by stating the shape of each action's return, which the annotations do not.

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: purpose plus actions, then sibling routing, then return values. Nothing is redundant, and the routing constraint that determines tool selection is front-loaded rather than buried.

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 9-parameter read-only tool with no output schema, the description covers purpose, selection criteria, and the return format for each action, which is enough to call it correctly. It does not address pagination behavior despite log exposing limit/offset, a minor residual 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 per-parameter syntax is already documented and the baseline is 3. The description goes beyond the schema by mapping each action value to a distinct output (chronological event array, structured changeset diff, session post-mortem markdown), which is semantics the enum listing alone does not convey.

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 ('append-only event audit ledger'), three concrete actions (log, changelog, post_mortem), and the returned artifacts. It is immediately distinguishable from siblings like manage_snapshots, which it explicitly positions itself against.

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 gives an explicit either/or routing rule: use get_events over manage_snapshots when examining the chronological sequence of mutations rather than restoring checkpoints. The parenthetical action list also tells the agent which sub-mode to select without opening the schema.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the destructive/import consequences are partly carried by structured metadata. The description adds the return payload types (serialized graph, trajectory dataset, synergy metrics, import statistics), which is useful, but it never states that import actions can overwrite or destroy existing data — a notable omission for a destructive tool.

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

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

Two tight sentences: the first front-loads the resource scope and action list, the second routes the agent away from query_graph, and a third short sentence covers return values. Dense but every sentence earns its place; the action enumeration is long yet necessary for a nine-action tool.

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

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

With 13 parameters, 100% schema coverage, and no output schema, the description sensibly supplies the return-value summary the output schema lacks and states the resource scope. It is complete enough to call correctly, though it leaves per-action parameter applicability to the schema descriptions.

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 only restates the action names already enumerated in the action enum and adds no syntax, format, or applicability guidance beyond what the schema documents (e.g., 'edges for import_graph').

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 gives specific verbs (export, import) and enumerates the four resource families (graph structures, issue tracker items, fine-tuning trajectories, synergy metrics) plus the full action list. It clearly differentiates from query_graph. It loses a point only because the tool is a broad nine-action facade whose scope is hard to hold in mind from prose alone.

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 explicitly names the alternative (query_graph) and the condition that selects this tool instead: bulk-transferring graph data or generating AI training datasets. It does not address the other import/export-adjacent siblings (manage_specs, manage_snapshots), so the 'when not' coverage is partial.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful context about VCS sync and return types, but it does not go beyond annotations to explain which actions overwrite data, what permissions are needed, or how conflicts are resolved. A 3 is appropriate given the annotations carry the main behavioral burden.

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, each earning its place: the first scopes the tool and lists actions, the second routes from a sibling, and the third summarizes return values. It is front-loaded and contains no redundant filler.

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

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

The description covers the tool's purpose, alternative sibling, and return values, and the annotations plus full schema coverage handle safety and parameter semantics. It does not explicitly map which parameters apply to which action, though the schema descriptions do this adequately. The definition is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so every parameter already has a semantic description in the schema. The description lists the actions but does not add syntax, format, or conditional logic beyond what the schema provides, making the baseline 3 correct.

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

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

The description states a specific verb and resource ('Physical SQLite database maintenance, backups, integrity checks, and Git VCS state sync') and enumerates all six actions. It also explicitly distinguishes itself from the sibling manage_snapshots, so an agent can tell what this tool does 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?

It gives explicit routing guidance: use manage_database instead of manage_snapshots when managing physical SQLite files, cross-branch merges, or database corruption audits. This names the alternative and the condition that selects it, leaving little to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so mutation semantics are covered structurally. The description adds value beyond that by disclosing the three distinct return shapes (created edge record, batch count, visual link confirmation), which matters because there is no output schema. It stops short of saying what a remove destroys or whether edges are recoverable.

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 with the action list front-loaded and zero filler; each sentence carries distinct information (scope, sibling routing, return shape). The action enumeration is mildly redundant with the schema enum but is defensible as orientation material.

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 12-parameter, nested-object, no-output-schema mutation tool, the description covers scope, sibling disambiguation, and expected returns, which are the main gaps an agent would hit. It leaves the batch_add edge object shape and link_visual prerequisites entirely to the schema, which is acceptable given 100% schema coverage.

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 all 12 parameters carry their own descriptions and the description need not re-document them. The description only restates the four action values already listed in the action enum's own description, adding no syntax or format detail 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?

States a specific resource ('typed graph relationships between nodes') and enumerates the four supported actions inline. It goes further by explicitly naming the sibling it is not (manage_nodes) and the boundary condition that separates them, so an agent can route correctly without opening either 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 'Use manage_edges instead of manage_nodes when...' sentence gives a clear selection rule against the most confusable sibling. It does not, however, explain when to pick add vs batch_add vs link_visual, leaving intra-tool action selection to the enum names.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is partly covered. The description adds the return-shape surface ('Returns node object, edge connections, batch results, or search matches'), which is useful given there is no output schema, but it never warns which actions mutate/destroy data (remove, batch_update) or mention the optimistic concurrency behavior implied by expected_version.

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 plus a short return-shape line, with the action enumeration and the sibling-routing rule front-loaded. No filler, though the parenthetical action list slightly duplicates the action enum in 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 21-parameter, 9-action, nested-object tool with no output schema, the description covers the action set and the return surface but omits action/parameter coupling (e.g. add_note requires attach_to/text, batch_update requires ids) and any warning that some actions are destructive. Adequate but with clear gaps for a tool this broad.

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% across all 21 parameters, so the schema already carries the parameter semantics; the description adds no per-parameter meaning beyond the action list. Baseline 3 is appropriate when the schema does the heavy lifting.

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 verb+resource ('Manage graph nodes in the state graph') and enumerates the nine supported actions, so an agent knows exactly what surface this tool exposes. It also explicitly distinguishes itself from the closest sibling by routing runnable task states to manage_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?

It gives an explicit when-to-use rule with an alternative named: 'Use manage_nodes instead of manage_tasks when operating on general node types (decisions, artifacts, plans, milestones, blockers) rather than runnable task workflow states.' That is clear routing context, but it offers no guidance on when to pick specific actions versus the overlapping query_graph sibling (e.g. search), and no exclusions for the destructive 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 declare write (readOnlyHint=false), non-destructive, non-idempotent. The description adds the return shapes (session record, bootstrap context snapshot, active session listing), which is useful context. However it does not disclose what 'end' does to state, permission needs, or idempotency behavior, so it stays at baseline-plus.

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 compact sentences, front-loaded with purpose and action list, then routing, then returns. No filler, though the parenthetical action list and schema already overlap slightly.

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 multi-action, 8-parameter tool with no output schema, the description covers purpose, action set, sibling routing, and return shapes. It is largely complete, though the destructive semantics of 'end' and per-action prerequisites remain unstated.

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 all eight parameters (including limit, active_only, session_id scope, task_limit) are already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb+resource (manage agent tracking sessions / multi-turn workflow attribution), enumerates the four actions (start, end, list, bootstrap), and explicitly contrasts itself with the sibling manage_tasks. An agent can distinguish this from manage_tasks without opening either 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?

It gives explicit routing: 'Use manage_sessions instead of manage_tasks when establishing agent session boundaries and tracking multi-turn workflows rather than individual work items.' That names the alternative and the deciding condition, but it offers no guidance on choosing among its own actions (start vs. bootstrap vs. list) or other 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 declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds return types but never clarifies that revert/undo mutate state while list/diff/get_state/get_history are safe reads, leaving mixed-action risk unstated.

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 tight paragraphs with the core capability front-loaded before the alternative and the return summary. The parenthetical action list is mildly redundant with the schema enum, but no sentence is wasted.

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 nine-parameter, seven-action tool with no output schema, the description supplies purpose, differentiation, action inventory, and return types, which is substantial. It lacks per-action parameter applicability (e.g., timestamp for get_state/revert), the one remaining gap for a tool this complex.

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

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

Schema description coverage is 100% and each parameter is documented, so the burden is on the schema. The description's restatement of the action list duplicates the enum and adds no mapping of which parameters apply to which action.

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?

States specific verbs and resources (state checkpointing, time travel, diffing, undo) and enumerates the supported actions, so an agent knows exactly what domain this covers. It explicitly distinguishes itself from the sibling manage_database, making it separable 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?

Explicitly routes the agent away from manage_database with a concrete condition: use this when reverting state graph mutations or comparing checkpoints rather than physical database file maintenance. It does not advise when to pick among the seven internal actions or when not to snapshot at all, so it stops short of a full 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 supply the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the agent already knows this is a non-destructive mutation surface. The description adds useful return-shape context (AST, compliance matrix, verdict, feature plan), which matters since there is no output schema. However it discloses nothing about per-action side effects, permissions, or whether operations are reversible, so it is only partially 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?

Two front-loaded sentences plus a return sentence, no filler. The action list is repeated in the description, the action enum, and the action property description, which is mild redundancy, but each sentence otherwise earns its place.

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

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

For a tool with 7 actions and 13 parameters, the description covers the routing question and the return types, and the schema covers parameters fully. What is missing is any per-action contextual detail, for example which parameters apply to ingest versus verify, leaving the agent to infer mappings from parameter names alone.

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

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

Schema description coverage is 100%, so each of the 13 parameters is already documented in the schema, including the action enum. The description only restates the action list and return types, adding no per-parameter meaning or per-action parameter mapping. Baseline 3 is appropriate when the schema does the heavy lifting.

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 domain (Spec-Driven Development) and enumerates the actions the tool performs, so the agent understands it handles SDD spec authoring, ingestion, and verification plus template generation. It distinguishes itself from the closest sibling, manage_nodes, which is strong. It stops short of 5 because the tool is a broad multi-action bundle and the description never sharpens what each action's purpose is.

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 gives an explicit routing rule: use manage_specs instead of manage_nodes when authoring, ingesting, or verifying formal SDD specifications against acceptance criteria. That is a clear when-to-use with a named alternative. It lacks per-action selection guidance (when to use verify vs compliance vs decompose_feature), which keeps it from 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 declare readOnlyHint=false with destructiveHint=false, and the description is consistent with mutation-triggering actions (complete, auto_prune). It adds useful disclosure of what each action returns, which annotations do not cover. However, it says nothing about side effects of auto_prune, whether completion/pruning is reversible, or permission requirements for a tool whose default action set includes mutations.

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-loaded with the action inventory then the routing rule then return values; no filler. It is dense but every sentence carries information, and the action list could arguably be deferred to the schema's enum.

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 20-parameter, multi-action tool with no output schema, the description supplies return-value orientation per action and a sibling-routing rule. The schema's per-parameter action scoping compensates for the missing action-to-parameter mapping. Remaining gap is the absence of any safety/reversibility note around the mutating 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% and each param description already scopes itself to an action (e.g., 'for find_stale', 'for find_similar_blockers'), so the schema does the heavy lifting. The description adds no syntax, format, or default detail beyond the schema, so the 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 enumerates the exact action set (next, complete, find_blocked, find_stale, find_blockers, find_similar_blockers, auto_prune) and names the resource domain, so an agent knows this is a task-lifecycle tool. It also differentiates itself from a sibling by name (query_graph). It stops short of a single crisp verb+resource statement, but coverage is strong.

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 gives an explicit routing rule: use manage_tasks instead of query_graph when querying runnable tasks by priority order or resolving execution blockers. That names an alternative and the selecting condition. It does not, however, explain when to prefer one action over another within the tool, nor any exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description reinforces 'safe read-only SQL,' which the schema already states, and adds only brief return-shape notes per action without disclosing permissions, limits, or scoping behavior.

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

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

Three sentences that are front-loaded with the tool's scope and routing rule. The parenthetical action list duplicates the enum already present in the schema, a minor redundancy, but nothing is bloated.

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

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

For an 11-parameter, multi-action tool with no output schema, the description does summarize the return shapes across actions and gives a routing rule. It falls short on mapping parameters to actions, but the schema covers parameters and the safety profile is fully annotated, making the definition largely sufficient.

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 11 parameters are already documented in the schema, which serves as the baseline 3. The description names the actions but adds no parameter-level detail (e.g., which params apply to which action) 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?

States a specific verb (Query) plus the resources it operates on (graph topology, neighborhoods, dependency paths, compact task slices) and enumerates its five actions. It explicitly distinguishes itself from the get_analytics sibling, so an agent can route 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 gives an explicit when-to-use/when-not rule: use query_graph for topology and path traversals rather than aggregated metrics, naming get_analytics as the alternative. It does not, however, guide selection among its own five actions (subgraph vs trace vs natural_language), leaving that to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation risk is flagged structurally. The description adds useful nuance by separating read-only diagnostics (validate/doctor/check_refs/audit_chain) from maintenance actions (compact/archive/prune_events/dedupe), but it never states that those actions irreversibly delete data, nor does it expose the dry-run default.

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?

Front-loaded with the verb and action set, followed by the sibling comparison and return values. The parenthetical action list largely duplicates the enum, which is mildly redundant, but the structure and length are otherwise 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?

For a 10-parameter, no-output-schema tool, the description covers what actions exist and what each returns (diagnostics, health report, repair log, Merkle chain audit, maintenance stats). It stops short of linking action-specific parameters (apply, auto_heal, dry_run) to their triggering actions, leaving that to the schema.

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

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

Schema description coverage is 100%, so all ten parameters (apply, dry_run, older_than, preserve_types, etc.) are already documented in the schema. The description restates only the action enum and adds no syntax, defaults, or cross-parameter constraints 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?

States a specific verb (run) plus the resources/actions involved (validate, doctor, check_refs, audit_chain, compact, archive, prune_events, version, dedupe) and explicitly names the sibling it is not (get_analytics). An agent can distinguish it from the other manage_* and query tools without opening a 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?

Explicitly routes the agent: 'Use run_diagnostics instead of get_analytics when performing database repair, AST reference auto-healing, or verifying SHA-256 event hash chains.' This is clear when-to-use guidance, but it does not state when NOT to run destructive actions or any prerequisites (backups, permissions).

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

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

Annotations already declare destructiveHint=true, non-idempotent and closed-world, so the safety profile is partly covered. The description adds genuinely new behavioral context by disclosing the return shapes (message payload, lease acquisition status, topic list, deletion confirmation) and the asynchronous/lease coordination model. It does not, however, say which of the seven actions is destructive or what deletion actually removes, which is the main remaining 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 purpose before the sibling disambiguation and return summary. The parenthetical action list duplicates the action enum verbatim, which is a small but real redundancy rather than a functional defect.

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 13-parameter, 7-action tool with no output schema, the description does carry the return-value information an agent would otherwise lack. What is missing is the mapping of which parameters apply to which action (e.g. id for get/delete, resource_id for lease), leaving the agent to infer that from parameter names alone.

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% across all 13 parameters, so the schema already documents each field including enum values and defaults. The description adds no per-parameter meaning beyond repeating the action enum, so the 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?

Names a concrete verb+resource ('Multi-agent shared blackboard') and enumerates the seven supported actions, which the agent can map directly onto the enum. It also explicitly distinguishes itself from the sibling manage_nodes, so an agent can route between them without opening either 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?

States an explicit when-to-use and when-not-to-use rule: 'Use use_blackboard instead of manage_nodes when exchanging transient inter-agent messages or mutex resource leases rather than recording persistent graph knowledge.' The alternative and the selecting condition are both named.

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