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 discloses batch/atomic semantics ('if any explanation is invalid, nothing is added and every problem is reported'), validation against a frozen diff, and line-copying behavior. It is missing only surrounding operational context such as permission or auth requirements.

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

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

Four compact sentences, front-loaded with the core action and scope, then guidance, then failure behavior. It is dense but every sentence carries usable information; the single long paragraph is only mildly heavy.

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 annotations and no output schema, the description covers purpose, inclusion criteria, output effect (lines copied onto the diff), and atomic failure behavior, which is enough for correct invocation. Return-value details are unnecessary given no output schema, leaving only minor gaps like auth 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?

Top-level coverage is 50%, but the nested item schema documents body, path, side, title, and line fields in detail. The description still adds semantics the schema does not spell out — that locations are checked against the frozen diff and their lines copied — which explains why exact path/line/side values matter.

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 and resource ('Explain blocks of added or removed code to the reviewer, as a batch') and immediately clarifies scope by contrasting with the sibling concept of findings ('problems go in findings'). An agent can tell this apart from add_findings 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 states when to create one ('every long (about 30 lines or more) or complex block') and when not to ('skip trivial code'), plus routing away from findings. It stops short of naming the update/delete siblings (update_explanation, delete_explanations) as alternatives for existing explanations.

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 discloses the atomic transaction semantics ("if any finding is invalid, nothing is added and every problem is reported") and the validation against the frozen diff with line copying. It omits auth/permission needs and return shape, but the failure behavior is unusually well spelled out.

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 with the core action and its batching nature front-loaded, followed by the failure contract and one kind-specific rule. Dense but every sentence earns its place; no filler.

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

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

For a batch-mutation tool with no annotations and no output schema, the description covers the essential behaviors an agent needs: batching, atomicity on invalid input, diff validation, and the requirement_gap case. Only the success return and any permission requirements are left unstated, which is a minor gap.

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

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

Top-level schema coverage is 50% (analysis_id documented, the findings array is not), but the nested item schema is richly documented for severity, kind, location, and suggestion. The description's only parameter-level addition is the requirement_gap hint, which largely repeats the kind enum's own description, so it adds little 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 verb+resource ("Record findings") and scope ("as a batch"), which cleanly separates it from single-item siblings like update_finding and from add_explanations. It stops short of naming which sibling to use instead, but the purpose is unmistakable.

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 one concrete usage directive ("Include requirement_gap findings for requested behaviour that is missing"), which implies the when for that kind. However, there is no guidance on when to batch-add here versus updating an existing finding (update_finding) or when this is preferred over other entry points.

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 discloses that the diff is 'frozen' (a persisted snapshot, not a live read), that working_tree includes the index, and what the return contains. It omits any permission/auth requirements or idempotency notes, keeping 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?

Two sentences, front-loaded with the purpose, then the mode semantics, then the return/follow-up. No filler; each clause conveys a distinct fact.

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

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

Covers mode behavior and return values even though no output schema exists, and notes the get_diff follow-up. Only minor gaps remain around permissions and long-term lifecycle, which siblings like get_analysis/delete_analysis imply.

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 value by explaining the parameter interactions: base...head semantics with head defaulting to HEAD, and mode-dependent acceptance. It reinforces the schema rather than merely repeating it.

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 an analysis') plus the concrete effect of the operation ('computes and freezes the git diff of the repository for human review'). It also distinguishes itself from the sibling get_diff by routing the agent there for reading the results.

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 a clear trigger ('once a feature is developed') and points to the follow-up tool ('then read them with get_diff'). It stops short of stating when NOT to use it or naming alternatives beyond get_diff.

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 behavioral burden and does disclose what is destroyed (the analysis and its frozen diff) and what is deliberately spared (the repository). It covers the edge case of removing an analysis flagged as unreadable. It stops short of stating irreversibility, confirmation requirements, or any permission/auth constraints.

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 with zero filler, and the core action plus its blast radius are front-loaded before the edge-case sentence. Every sentence earns its place.

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

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

For a one-parameter delete tool with no output schema and no annotations, the description supplies the key information: destructive scope and the untouched boundary. It lacks only irreversibility/permission context, which is a minor gap given the tool's simplicity.

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

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

Schema coverage is 100% and the single analysis_id parameter is already documented in the schema as coming from create_analysis or list_analyses. The description adds nothing about the parameter, 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?

States a specific verb ('delete') and resource ('analysis'), plus the coupled artifact ('its frozen diff'), which cleanly separates it from siblings like delete_findings or delete_explanations. The scope note that the repository is not touched further pins down what is and isn't affected.

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 destructive verb rather than stated: there is no explicit 'use this when you want to permanently remove an analysis' or routing to alternatives such as update_analysis or refresh_analysis. The repository-untouched note gives partial scope guidance but is not a when-to-use rule.

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 are provided, so the description carries the full behavioral burden for a destructive operation. It does not say whether deletion is permanent, whether it cascades to findings or explanations attached to the diagram, or what permissions are required. Only the bare mutation intent is conveyed.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though it is arguably too terse for a destructive 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?

For a delete operation with no annotations and no output schema, the description should at least address irreversibility or side effects. It leaves an agent unable to judge the consequences of invoking it.

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 explains that diagram_id comes from get_analysis and analysis_id from create_analysis/list_analyses. The description adds no parameter meaning 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?

States a specific verb and resource (delete a diagram) and scopes it to an analysis, so the action is unambiguous. It does not explicitly distinguish itself from similarly named siblings like delete_analysis or delete_findings, but the resource noun carries the differentiation.

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

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

No guidance on when to use this tool, no prerequisites, and no mention of alternatives such as delete_analysis or set_diagram. The agent must infer usage entirely from the name and 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?

With no annotations, the description carries the full burden, and it usefully discloses all-or-nothing semantics ('If any id is unknown, nothing is deleted') — non-obvious transactional behavior. However, it says nothing about irreversibility, permission requirements, or whether deletions cascade to related records, which matters for a destructive 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?

Two short sentences, zero filler, with the operation front-loaded and the edge-case behavior immediately after. Nothing could be cut without losing 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 destructive tool with no output schema, the description is close to sufficient: it covers scope and failure semantics. It falls short only on irreversibility and permission/confirmation expectations, which arguably an agent should still know before invoking a delete.

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 both parameters are documented in the schema, so the baseline is 3. The description adds no syntax, format, or batching nuance beyond 'by id' for either analysis_id or explanation_ids.

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 ('Delete explanations by id') that distinguishes it from the sibling deletes (delete_findings, delete_analysis, delete_diagram). The agent can identify exactly what gets removed 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?

Gives a concrete triggering context ('when the code they describe is gone'), which is more than most delete tools offer. It does not name an alternative tool or state when-not to use it, but the resource-scoped siblings make the choice fairly unambiguous.

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. It does disclose a genuinely non-obvious transactional trait: 'If any id is unknown, nothing is deleted' (all-or-nothing atomicity). However, it never states that deletion is permanent/irreversible or what permissions are required, so the destructive profile is only partially covered.

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

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

Two short sentences, zero waste, with the primary action front-loaded and the atomicity caveat as a tight trailing clause. Nothing redundant.

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 low-complexity, no-output-schema two-param tool this is close to sufficient, and the atomicity note is valuable. But with no annotations the description should also say the deletion is irreversible and whether it is a hard or soft delete — an agent cannot infer that from the structured fields.

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 both required params (analysis_id, finding_ids) are documented in the schema, so baseline is 3. The description adds no syntax, ID-format, or batch-limit 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?

States a specific verb+resource ('Delete findings by id') and the sibling-set context (findings vs. explanations/analysis) makes the target clear. It is distinguishable from delete_analysis and delete_explanations without opening a schema, though it does not explicitly name the boundary.

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

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

Provides real workflow context: 'typically once refresh_analysis shows them solved,' which names a sibling tool and the condition that motivates the call. No explicit when-not guidance or alternatives are given, so it stops short of 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?

With no annotations, the description carries the full behavioral burden and does much of it: it discloses the rich return shape (files reviewed or not, findings with status/location, diagrams flagged on layout crossings) and the read-only nature implied by 'Read'. It stops short of explicitly stating there are no side effects or any permission requirements, so it is strong rather than complete.

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 what the tool reads, and no filler. The long enumeration is dense but each item is load-bearing given there is no output schema to describe the return value.

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

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

No output schema exists, so the description must define the return contract itself, and it enumerates the payload comprehensively (project through review state, including the diagram-crossing flag). Nothing an agent needs in order to call and interpret this tool 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?

There is exactly one parameter at 100% schema coverage, and the schema already documents it ('as returned by create_analysis or list_analyses'). The description adds no format, constraint, or edge-case detail beyond the schema, which is the expected baseline when the schema does the work.

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?

Specific verb and resource with explicit scope; clearly separable from its read-only siblings.

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?

'Use it to check what is already recorded before adding more' gives a clear read-before-write context, which is genuinely actionable. It stops short of naming alternatives or exclusions, but the whole-analysis scope implicitly separates it from the narrower reads in the sibling list.

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 meaningful traits the schema cannot: the diff is 'frozen' (an immutable snapshot rather than live state) and it carries old and new line numbers per line. It omits error behavior for an invalid analysis_id and any size/truncation limits, which keeps it from 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?

Two dense sentences, front-loaded with the resource and scope, with zero filler. Every clause adds information an agent needs.

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 no annotations, so the description must describe the return shape, which it does (old and new line numbers per line). It leaves gaps around failure modes and behavior on very large diffs, but is otherwise complete for a read-only inspection tool.

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

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

Schema coverage is 100%, so baseline would be 3; the description still earns extra credit by explaining the two-column line-number output and which column to use for downstream locations. The path default it mentions is largely redundant 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?

States a specific verb ('Read') and resource ('the frozen diff'), plus the exact scope: one file, or all files when path is omitted. An agent immediately knows what this returns and how scope is controlled, 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?

Gives clear conditional guidance ('or of every file when path is omitted') and, unusually, cross-tool guidance that the NEW-side column must be used for finding locations and diagram node lines. It does not name alternatives or exclusions (e.g. when to prefer get_analysis), so it stops short of 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?

With no annotations, the description carries the full burden and mostly delivers: it declares 'Read-only' (substituting for readOnlyHint), describes two behavioral modes (pre- vs post-submission), and flags that refresh_analysis discards the data. It stops short of covering error cases, permissions, or response shape when feedback does not yet exist.

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, front-loaded with the primary purpose, then the pre-submission variant, then the ordering hazard. Every sentence carries distinct information with no repetition.

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

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

There is no output schema and no annotations, so the description is the only source of return-value and safety information — and it covers both the post-submission payload and the pre-submission progress state adequately. A brief note on what happens with an invalid or unknown analysis_id would make it fully complete.

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

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

Schema description coverage is 100%, and the single analysis_id parameter is documented in the schema as coming from create_analysis or list_analyses. The description adds no extra meaning about the identifier, 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 specific verb (read) and resource (the reviewer's feedback) and enumerates the payload: decision, selected findings and notes, and the prompt to act on. It also distinguishes itself from get_analysis by describing state-dependent content, and explicitly names refresh_analysis as the contrasting sibling.

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 an explicit when: after submission you get the final feedback, before submission you get progress. It also gives a hard ordering rule — 'Always read the feedback before calling refresh_analysis, which discards it' — naming the alternative and the consequence of sequencing incorrectly.

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 are provided, so the description carries the burden, and it does disclose the full return shape including the enumeration of review states, which is genuine behavioral context. It stops short of stating read-only safety explicitly or any pagination/permission behavior, but 'List' strongly implies a read.

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, well front-loaded with the return content before the routing advice. The second sentence is dense but every clause earns its place by naming a sibling and its condition; no 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?

With no output schema, the description compensates by enumerating the returned fields, and with no annotations it supplies routing context for a read-only list tool. It is essentially complete for invocation, lacking only minor operational details like pagination or error behavior.

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

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

Schema coverage is 100% and the schema already explains the project filter, including the useful 'unknown name lists existing projects' fallback. The description adds no parameter meaning 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?

States a specific verb (List) and resource (analyses), then enumerates exactly what the listing contains: refs, open findings by severity, reviewed files, diagram count, and review state with its four values. This is clearly separable from get_analysis and the other sibling tools.

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

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

Explicitly frames itself as the entry point ('Start here') and names the alternatives with their triggering conditions: update_analysis to rewrite the overview, refresh_analysis after code changes, create_analysis for a different feature or diff. Explicit when-to-use and when-not-to-duplicate 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 full burden and does well: it discloses the no-op behavior when already registered, the force override, and that it avoids restarting the MCP server. It does not mention permissions or side effects on an existing GUI worker, 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?

Three tight sentences, front-loaded with the action, then the trigger condition, then the edge case. No filler and every sentence carries distinct information.

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

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

For a single-optional-parameter operation with no output schema and no annotations, the description covers purpose, trigger, and the already-registered edge case. Nothing required to invoke 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 force parameter is already documented. The description still adds practical meaning by framing force as the override for the otherwise-no-op path ('Does nothing... unless force=true'), complementing the schema's phrasing rather than merely repeating it.

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 pair (relaunch, re-register) with clear resources (GUI worker, proxy server). There are no functionally similar siblings in the list, and the tool's unique identity as the GUI/proxy reconnection mechanism is unambiguous.

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

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

Explicitly names the triggering condition: 'use this when the proxy server was not running when the MCP server started (so the GUI registration failed)'. It also states the negative case ('does nothing if the GUI is already registered, unless force=true'), which is exactly the when/when-not guidance an agent needs.

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 discloses that changed files become unreviewed, changed findings become outdated, the review reverts to pending, and prior feedback is discarded. It omits idempotency, permission requirements, and cost, which keeps it from 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?

A single sentence that front-loads the action, then the state consequences, then the prerequisite tool. Every clause earns its place, though the semicolon-chained structure is dense.

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 mutation tool with no annotations and no output schema, the description covers the critical side effects an agent must know before calling. It does not describe what the call returns, but that gap is minor given the destructive-behavior disclosure is thorough.

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?

Only one parameter and schema coverage is 100%, so the schema already documents analysis_id fully (including its origins in create_analysis/list_analyses). The description adds no syntax or format meaning beyond that, 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?

States a specific verb+resource ('Recompute the frozen diff') and immediately pins the scope ('same repository, mode and refs'), which distinguishes it from create_analysis and update_analysis. It also names the sibling get_review_feedback, so an agent can route without inspecting schemas.

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 a clear triggering condition ('after fixing the code') and a prerequisite action ('read it with get_review_feedback first'), which is strong context. It stops short of stating when-not to use it or naming a full alternative, so it falls short of 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?

With no annotations, the description carries the full burden and does so: it discloses the destructive 'fully replace' semantics of passing diagram_id, the division of labour (agent supplies nodes/links only, GUI handles layout and status colours), composition rules (one subject, 5-12 nodes, zero crossings), refusal conditions (mindmap with a cycle or multiple roots), and what the response reports back with remediation advice.

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?

It is front-loaded with purpose and the three kind behaviors, which is good, but it is very dense and a large share of it duplicates the `kind` and `nodes` schema descriptions word-for-word. Those sentences do not earn their place given they are already structured-field content.

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

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

For a complex 7-parameter tool with no annotations and no output schema, the description covers kinds, composition constraints, replacement semantics, and the shape of the returned crossing/advice feedback, which compensates for the missing output schema. Minor gaps remain around permissions and the mismatch between the schema's minItems and the stated 5-12 node rule.

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 largely restates schema content -- the `kind` enum text and the nodes reading-order/5-to-12 wording appear verbatim in the schema -- and adds only marginal extras such as 'no coordinates or colours' and 'declare nodes in reading order'. It does not compensate for the schema's misleading minItems of 1 versus the stated 5-12 range.

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 first clause names a specific verb and resource ('Create a diagram, or fully replace the one with diagram_id') and adds the reviewer-facing purpose. An agent can immediately tell this is the diagram-creation/replacement tool, distinct from delete_diagram in the sibling list.

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 a clear when-to-use trigger ('when a picture helps the reviewer') with concrete examples (impact perimeter, process flow, concept map) and explains which `kind` fits which situation. It stops short of explicit when-not guidance or naming alternatives such as emitting findings or explanations 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. It usefully discloses partial-update semantics ('fields left out are kept') and content expectations, but says nothing about permissions, whether the analysis must exist, error behavior, or the response. Adequate but incomplete for a 9-parameter mutation 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 sentences, front-loaded with the field list and then content guidance. The middle sentence is dense and slightly overloaded with parentheticals, but 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?

All 9 parameters are fully documented in the schema and there is no output schema to explain, so the description only needs the workflow and patch semantics it already provides. Missing only permission/error context, which is minor here.

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 conceptual meaning the schema lacks: that 'overview' is composed of objective+approach+attention_points, and that summary is one bullet per change, not per file. This mapping value exceeds 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 states a specific verb (change/update) plus resource (analysis) and enumerates the updatable fields (title, project, overview, summary, initial request). Purpose is unmistakable, though it does not explicitly differentiate itself from siblings like update_finding or update_explanation beyond the resource noun.

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 real workflow context ('Right after reading the diff, write the overview... and the summary') plus the patch constraint ('Give at least one field; fields left out are kept'). It does not name alternatives, but the timing guidance is concrete and actionable.

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

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

With no annotations, the description carries the full burden and does disclose a genuinely non-obvious behavior: location updates are validated against the diff and can make an outdated explanation current again. However it says nothing about partial-update semantics (whether omitted fields are left unchanged), failure modes for an invalid location, or required permissions.

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

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

Two tightly packed sentences, front-loaded with the core action and then the diff-validation consequence. Dense but every clause carries information; no filler.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description covers the key behavioral twist (diff-checked location) but leaves partial-update semantics, error behavior, and return expectations unstated. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters thoroughly. The description adds the useful framing that path/start_line/side form a single 'location' concept tied to the diff check, but does not extend the per-parameter meaning beyond what the schema provides.

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

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

States a specific verb+resource ('Change one explanation') and enumerates the mutable facets (title, body, location), which cleanly separates it from the sibling update_analysis and update_finding tools. It does not explicitly name those siblings, 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?

Gives conditional usage guidance: a new location is diff-checked and can revive an outdated explanation, and the body should be rewritten when the code changed. This is actionable context, though it never states when-not to use the tool or names an alternative 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, the description carries the full burden and does well: it discloses the side effect that a new location reopens an outdated finding, the null-clears semantics, and that the ignored flag is immutable here. It does not state permission/auth requirements or failure behavior for invalid locations.

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 and the field list, with side-effect caveats packed into the second sentence. Dense but no wasted filler.

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

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

For an 11-parameter mutation tool with no annotations and no output schema, the description covers the important side effects (reopening, null removal, ignored immutability) that an agent cannot infer from the schema. Remaining gaps are minor.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the null/removal semantics for path and prompt. The description's field enumeration largely restates what the schema provides, 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?

States a specific verb ('Change the fields of one finding') plus the exact field set (severity, kind, title, body, location, suggestion, prompt), so an agent can distinguish it from update_explanation or add_findings. It does not explicitly name or contrast a sibling tool, which keeps it 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?

Gives concrete usage conditions: a new location is validated against the diff, path null removes the location (requirement_gap only), and ignored status cannot be changed here — a clear exclusion that routes the agent elsewhere. It stops short of naming which alternative tool handles the excluded case.

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