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

With no annotations, the description carries the full disclosure burden and does so thoroughly: it identifies the operation as an in-memory virtual mutation, states that pre-flight policy checks run against .graphenium/policy.json, names the PRE_FLIGHT_VIOLATION failure mode, notes the target_symbol-missing failure records nothing, and declares duplicate calls idempotent. This is behavioral context an agent could not get from structured fields.

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 constraint and prerequisite are front-loaded before the behavioral detail, which is the right order. The closing sentence 'Returns a success confirmation or a structural violation error' largely restates the earlier pre-flight violation paragraph, so one sentence does not fully earn 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?

There is no output schema, and the description compensates by summarizing return outcomes (success confirmation vs. structural violation error). Combined with prerequisites, side effects, and idempotency, an agent has everything needed to invoke this correctly on the first attempt.

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 meaning beyond the schema: plan_id must come from a prior create_planning_workspace call, and target_symbol must reference an existing node or nothing is recorded. It does not elaborate on relation values (no enums present) or file_path format, which keeps it short of a 5.

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 specific verb and resource plus scope: 'Register an intended new or modified symbol and its dependency edges in a virtual planning workspace.' It explicitly distinguishes itself from mutate_graph by name, so an agent can separate the virtual/planned path from the physical-index path without opening any 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 states both when to use it ('declare your architectural design before writing code') and when not to ('Do NOT use mutate_graph ... for planned changes'), and names the required predecessor tool create_planning_workspace. The routing decision is fully specified with no inference left to 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?

With no annotations, the description carries the full burden and does so well: it declares this is a mutating operation, explains it initializes an empty Virtual AST in server graph state, notes immediate disk persistence and session lifetime, and discloses idempotency behavior when plan_id already exists. That is exactly the safety and side-effect context an agent needs before invoking a write 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?

Purpose, ordering, exclusion, side effects, idempotency, and return value are front-loaded in five tight sentences with no filler. Each sentence adds distinct decision-relevant information.

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

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

For a two-parameter mutation tool with no output schema and no annotations, the description covers invocation conditions, side effects, idempotency, and the return value ('workspace ID on success'). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real semantic value by explaining that plan_id collision yields idempotent reuse of the existing workspace, and that the workspace is associated with the provided plan_id. The description parameter's purpose is left to the schema, hence not a 5.

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 and resource ('Create a new virtual planning workspace'), and explicitly distinguishes itself from the sibling tools add_planned_symbol and validate_plan by naming them as follow-on steps. An agent can identify this as the initialization step without opening any 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?

Gives explicit when-to-use ('first when starting any multi-file feature or refactoring task, before calling add_planned_symbol or validate_plan') and when-not-to-use ('Do not use this tool if a plan already exists for your current task'). The ordering relative to siblings is fully spelled out.

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

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

With no annotations at all, the description carries the full disclosure burden. It does credibly describe the shape of the response (overview vs per-community focus, appended member lists and hub nodes), but says nothing about prerequisites (e.g. the graph must already be loaded/reloaded), cost/latency of an aggregation over the whole repo, or default limits behavior beyond what the schema states.

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

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

Two sentences, no filler, with the core output contract front-loaded and the mode-switching flags grouped in the second sentence. Every clause 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 10-parameter, no-output-schema tool it does the important work of describing what comes back, and the schema fully covers the knobs. What is missing is operational framing: no note that the repository graph must be loaded, and no hint about the relative cost of the repo-wide overview versus a focused community query.

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 one of the 10 parameters is already documented. The description echoes the semantics of community_id, include_community_members and include_god_nodes, but adds no detail the schema lacks (defaults, ranges, and filtering modes on node_types/path_prefix/generated_code_mode are all schema-side). 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?

A concrete verb (return) plus resource (repository-level architecture summary) and an explicit enumeration of what the payload contains: communities, cross-community connectors, architectural hotspots. It does not distinguish itself from nearby read tools such as query_graph or get_graph_info, which is the only thing keeping it off a 5.

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 second sentence gives conditional guidance for three flags ('Set community_id to focus on one community instead of the overview', include_community_members/god_nodes append to the result), so invocation modes are implied. There is no statement of when to choose this tool over an alternative query path, nor any when-not guidance.

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

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

With no annotations, the description carries the burden and does well: it declares the always-returned payload and which optional reports are appended by each flag. It stops short of stating that the tool is read-only or noting any cost/latency of the heavier reports.

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, front-loaded with the guaranteed return set before the opt-in behavior. The second sentence is a long enumeration but each clause maps to a distinct flag, so little 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?

No output schema exists, and the description compensates by listing the always-present fields; it also explains all four opt-in reports. Adequate for a 9-param, zero-required diagnostic tool, with only the scoping/filter parameters left entirely 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 coverage is 100% and each parameter already has a description, so the description's flag summary largely restates it. It adds grouping value by pairing each include_* flag with the report it appends, but the scoping params (node_types, path_prefix, exclude_path, generated_code_mode) go unmentioned at the tool level.

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 and resource ('Return graph metadata, health, and diagnostics in one call') and enumerates exactly what comes back, so an agent knows what it gets. It does not explicitly distinguish itself from the nearby get_architecture_summary or query_graph siblings, which would have made it a 5.

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 'in one call' and the opt-in flags, but never says when to reach for this versus get_architecture_summary, query_graph, or reload_graph, and gives no exclusions. Useful but inference-required.

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

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

With no annotations, the description carries the full burden and does state the read-only nature and the key behavioral trait: flag combinations can produce large responses and consume context budget. It does not mention error behavior, truncation, or what happens when target is ambiguous, which keeps it short of a 5.

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 purpose and routing rule, then cost advice; every sentence has a job. It runs slightly long, and the flag-advice sentence partially repeats guidance implied by the schema's default-false flags.

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 tool with no output schema, the description explains the response shape (baseline node details plus appended blocks) and when to add each. Adequate for correct invocation, though the include_callers mismatch and lack of note on how group_by/show_leaves interact with include_file_summary slightly reduce confidence.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by explaining the baseline-vs-optional-block model and the cost tradeoff of setting multiple flags. One caveat: it says include_callers 'appends all incoming dependencies' while the schema says containers/imports/inheritance/implementations, a slight semantic mismatch that could mislead.

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 and resource ('Inspect a symbol and retrieve its structural neighborhood and metrics') and immediately clarifies the baseline return ('canonical node details') versus optional blocks. An agent can distinguish it from query_graph, trace_path, and get_architecture_summary 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 names the situation to use it ('primary orientation step before modifying a specific class, function, or module') and the alternative plus the exact selection condition ('use this instead of query_graph when you already know the exact target ID'). This is a genuine routing rule, not implied 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?

No annotations exist, so the description carries the full burden. It does disclose a key behavioral trait — that successful mutations persist to disk immediately — but says nothing about reversibility, what happens on a failed or partial mutation, idempotency of duplicate add_node/add_edge calls, or whether the in-memory graph must be refreshed via reload_graph afterward.

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: the first commits to what the tool is, the second is a tightly parallel action-by-action breakdown. Every clause earns its place and the general purpose is front-loaded before the detail.

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

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

For a 12-parameter tool with conditional per-action fields and no annotations or output schema, the description covers the action taxonomy and persistence but leaves real gaps: no per-action parameter requirements, no indication of what is returned on success, and no mention of interaction with the sibling reload_graph.

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 documents all 12 parameters, which sets the baseline at 3. The description adds action-level semantics that the flat schema enum does not (what each action accomplishes), but it never states which parameters are conditionally required per action — e.g. that add_edge needs source/target or that remove_edge accepts an optional relation filter.

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+resource ('apply a manual mutation to the relational index') and then enumerates all four actions with concrete semantics (add_node registers a concept/rationale, add_edge records a verified relationship, remove_edge deletes a stale edge, recluster re-runs community detection). This clearly separates it from read-oriented siblings like query_graph, get_graph_info, and inspect_symbol.

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?

Each action value is paired with the situation that selects it (e.g. remove_edge for 'a stale or false-positive edge', recluster to 're-run community detection'), which is strong intra-tool routing. However, there is no guidance on when to prefer this over the write-ish sibling add_planned_symbol, nor any exclusion such as 'do not use for bulk imports — use reload_graph instead'.

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

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

With no annotations, the description carries the full burden and does well: it declares the tool read-only, explains that scoring is keyword-based and traverses neighborhoods via BFS/DFS, and states that output is a structured Markdown report truncated to the token budget. It stops short of covering edge behaviors such as empty results, error handling, or determinism, so it is strong but not exhaustive.

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 usage, then adds mechanism, output format, and truncation behavior. Every sentence contributes useful information, and there is 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?

Although there is no output schema, the description explains the return format as a structured Markdown report and notes budget-based truncation. Combined with the fully documented input schema and explicit alternatives, it gives an agent enough context to call 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 description coverage is 100%, so the schema already documents all 13 parameters. The description repeats a few defaults such as BFS/DFS and budget=2000, but adds little parameter meaning beyond what the schema provides; the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: query the relational index with keywords to find nodes and explore topology. It also distinguishes the tool from siblings by naming inspect_symbol for known IDs and trace_path for deep multi-hop traversal.

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 gives the use case for this tool (initial discovery when exact node IDs are unknown) and names two alternatives with the conditions that select them. That is enough routing guidance for an agent to choose among the primary query options.

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

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

With no annotations, the description carries the burden and does well: it discloses the live-state-mutation effect (index is replaced in a running server) and that the default source is the launch-time path. It stops short of stating failure behavior (invalid path, parse errors) or whether the previous index is restored/discarded on failure, which matters for a state-replacing operation.

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

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

Three tight sentences: what it does first, the default behavior second, the use cases last. Every sentence earns its place and nothing is padded.

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 one-optional-parameter operational tool with no output schema, the description covers purpose, default source, and motivation. The remaining gap is operational edge cases (what happens if the path is invalid or the file is malformed, and whether the server's current index survives a failed reload).

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 schema already documents graph_path including the omitted-path default, so the description's sentence about the default merely restates it. The phrase 'a different repository's graph' adds slight semantic color (what a path typically points to) but no format or validation detail.

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 and resource ('Reload the relational index from a graph.json file') plus the key property that it happens 'without restarting the MCP server'. No sibling tool does anything comparable, so it is trivially distinguishable from the query/analysis tools listed.

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 gives two named scenarios for use: pointing a running server at a different repository's graph, and picking up changes after re-running `gm run`. That is exactly the when-to-use guidance an agent needs for an operational 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?

With no annotations, the description carries the full burden and does well by disclosing the step budget (max 10,000 steps), pre-loaded standard predicates, and support for rules, goals, facts, and negation. It stops short of explicitly stating read-only behavior or describing the result shape, which are minor but real gaps.

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

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

The description is front-loaded with the core purpose, then uses a compact bulleted list for predicates and a short sentence for base relations and constraints. Every sentence contributes useful information without repetition 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?

For a complex Datalog query tool with no annotations and no output schema, the description provides strong input-side context: syntax features, standard predicates, base relations, and budget bounds. It is complete enough to invoke correctly, though it does not explain the return format or how to choose this tool over siblings.

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 documents both parameters. The description adds substantial meaning for the query parameter by enumerating standard-library predicates and base EDB relations, which materially helps an agent construct valid queries. The step-budget behavior is also mentioned consistently with 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 opens with a specific verb and resource: 'Run a logic query over the codebase graph.' It further clarifies the query language and available predicates, making the tool's purpose concrete. It does not explicitly differentiate itself from siblings such as query_graph or trace_path, so it falls short of a 5.

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 listing standard predicates and supported Datalog constructs, which suggests the tool is for recursive or logic-based graph queries. However, it gives no explicit when-to-use/when-not-to-use guidance and does not name alternatives like query_graph or trace_path.

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

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

With no annotations provided, the description carries the full disclosure burden and does well: it declares the tool read-only, explains that traversal halts at depth, and that output is truncated to a character budget. It stops short of describing error conditions or how confidence scores are computed, leaving a minor 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?

The text is front-loaded with purpose, then routing guidance, then mode enumeration, then return format and limits. It is dense and information-rich, though the mode list makes it longer than strictly necessary for a first read.

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 15-parameter tool with no annotations and no output schema, the description supplies what an agent needs: mode semantics, depth/budget behavior, and the shape of the returned Markdown report. Gaps remain around failure behavior and the many shortest-path tuning filters, which are left entirely 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 coverage is 100%, so the baseline is 3; the description earns above that by adding semantic meaning the schema does not, such as what 'safest' optimizes for (highest aggregate confidence) and what transitive_forward vs transitive_reverse traverse. It does not explain source/target interaction beyond mode requirements, so it is not a 5.

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 specific verb and resource ('Trace connectivity and multi-hop paths across the codebase architecture') and immediately distinguishes its role from siblings by naming query_graph and inspect_symbol. An agent can tell what it 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 both positive triggers ('map blast radius, find shortest paths, or verify transitive layering') and an explicit routing rule ('use this instead of query_graph or inspect_symbol when you need to prove deep, multi-hop relationships'), then enumerates the five modes so the agent knows which variant answers which question.

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

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

With no annotations, the description carries the full burden, and it does disclose substantive internals: the Louvain modularity delta gate and surprise analysis always run, and policy rules are applied conditionally. However, it never says whether validation mutates workspace state or is a pure read, nor what happens on failure — the most important behavioral facts for a gate 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?

Three short sentences, zero filler, with the core action front-loaded and the conditional policy behavior placed last. Every sentence carries information.

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

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

For a validation gate with no output schema and no annotations, the description explains what checks run but not what the agent receives back (pass/fail, violation list, modularity numbers) or whether the workspace is modified. That leaves a meaningful gap for an agent deciding how to act on the result.

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 every parameter including defaults is already documented. The description adds only marginal meaning by naming the gates that modularity_tolerance and surprise_threshold feed into; it adds no syntax, ranges, or interaction details beyond the schema. 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?

States a specific verb and resource ('Validate a planning workspace') plus the lifecycle position ('before writing code'), which makes it distinguishable from graph-inspection siblings like get_architecture_summary or query_graph. It does not explicitly contrast itself with the closest sibling, verify_changes, so it stops short of a 5.

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

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

The phrase 'before writing code' gives clear timing context for invocation, and the skip_policy_rules clause implies a lighter-weight mode. There is no explicit statement of when not to use it or which sibling to prefer for post-change verification.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the report sections and how optional inputs change the output, but it does not state whether the operation is read-only, what permissions or prerequisites are required, or how failures are reported.

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 tight sentences with no wasted language. The core purpose is front-loaded, followed by return contents and conditional input effects.

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 seven-parameter tool with no output schema and no annotations, the description does a good job naming the returned report sections and explaining how optional inputs add sections. It is not fully complete because it omits safety/read-only behavior and does not explain the change-gate thresholds beyond what the schema provides.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters. The description adds some conditional meaning for plan_id, snapshot_name, and graph paths, but it does not mention max_ambiguous or min_resolution and largely repeats what the schema already says.

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: verify a change and return a unified report with named sections. It is clear what the tool does, but it does not explicitly distinguish itself from sibling tools such as validate_plan or inspect_symbol.

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?

Usage is implied by the phrase 'Verify a change' and by conditional notes about plan_id, snapshot_name, and graph paths. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative for cases where another sibling tool would be more appropriate.

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