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

Beyond the annotations, the description discloses the exact mutation scope: it adds a token definition and replaces only the specified line without touching other lines. It also explains that force_create bypasses duplicate detection, which is important behavioral context for a destructive, non-idempotent 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?

The description is front-loaded with the core action, then uses a short numbered list to explain effects and a compact Args section for parameters. Every sentence provides useful information for correctly invoking a destructive mutation 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 seven-parameter destructive tool with no schema descriptions, the definition covers purpose, scope, prerequisite usage, parameter meaning, and the risky force_create behavior. An output schema exists, so the brief return-value sentence is 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 description coverage is 0%, so the description carries the full burden and does so well. It documents every parameter, gives examples for file, value, token_name, and preferred_token_file, specifies that line is 1-indexed, and states the valid token_type values.

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

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

The description states a specific verb and resource: convert a hardcoded value into a design token. It also explains the two concrete effects, adding a token definition and replacing exactly the specified line, which clearly distinguishes it from broader mutation tools like replace_pattern or set_token.

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 prerequisite by telling the agent to use list_tokens() first to find hardcoded values. It also warns that force_create should be used only for testing. It stops short of explicitly naming when to use this instead of set_token or replace_pattern, so it is strong but not fully alternative-aware.

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

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

The 'Side effects: None (strictly read-only AST inspection)' line largely restates readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which the annotations already establish. The genuinely additive behavioral detail is that it returns a compact, categorized report specifically to avoid context-window exhaustion, which tells the agent the output is deliberately abbreviated. That one useful disclosure, plus the AST-implementation note, keeps it above the floor rather than at it.

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 one-line purpose, then cleanly sectioned into When to use / When NOT to use / Side effects / Args, so an agent can scan to the relevant block. It is slightly longer than necessary because the 'Side effects: None' block duplicates annotation data and the Args block overlaps the schema defaults.

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

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

For a read-only analysis tool with an output schema, everything needed to invoke it correctly is present: selection guidance, exclusions, safety profile, and the meaning of all three parameters. The only gap is a definition of what makes a token 'scattered' or how results are thresholded, which would help an agent interpret the report.

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 0%, so the description carries the burden and does so for all three params: it enumerates the category values ('all', 'colors', 'dimensions', 'strings') that the schema only types as an unconstrained string, clarifies that limit is files returned per category (not total), and marks project_root as optional. It does not explain what the 'all' category aggregates vs. individual categories, which is the one remaining ambiguity.

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: 'Analyzes scattered hardcoded design tokens (colors, dimensions, strings) across the project.' The parenthetical names exactly what kinds of literals are in scope, and later lines distinguish it from find_token_by_color, list_tokens, and set_text, so an agent can pick it over siblings 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?

Explicit when-to-use triggers are given (project onboarding, architecture audits, before major UI refactorings) and explicit when-NOT-to-use cases name the correct alternatives: find_token_by_color or list_tokens when the exact token/file is known, and set_token/add_token/set_text for applying changes. Nothing is left 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 and idempotentHint=true, so the safety profile is known. The description adds concrete consequences beyond that: journal entries are removed and backups are permanently cleared with no rollback. It does not mention whether approval can partially fail across files, 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 'Destructive:' and organized into labeled sections, which is easy to scan. The destructiveness/irreversibility is restated three times (header, when-not-to-use, side effects), slightly more repetition than needed.

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?

An output schema exists, yet the description still briefly confirms the return (JSON confirmation string). Combined with use conditions, alternatives, and side effects, nothing an agent needs before calling 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?

The tool takes zero parameters, so the baseline is 4; the description correctly notes 'Parameters: None.' and leaves nothing ambiguous.

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 with explicit scope: 'Approves ALL pending changes permanently' across all modified files. The all-files scope is distinguished from the single-file sibling approve_file_changes.

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?

Explicit when-to-use ('all modifications from recent operations are verified and accepted'), when-not-to-use ('No rollback after this action'), and names two concrete alternatives: approve_file_changes for single files and reject_all_files to discard.

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 and idempotentHint=true, so the description's extra detail is genuinely additive: it explains that the hunk is merged into the file's baseline backup while other changes remain pending. That state-change disclosure is exactly what an agent needs before a destructive call; only permissions/irreversibility detail is missing.

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?

Labeled sections (What it does / When to use / Parameters / Returns) with the core action front-loaded in the first line. Every sentence carries distinct information; nothing is padding.

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 2-param destructive mutation, the description covers action, scope, triggering condition, parameter meaning, and return shape, which is ample. Since an output schema exists, the Returns line is somewhat redundant but harmless; missing detail on failure modes or permission requirements keeps it short of a 5.

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

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

Schema description coverage is 0%, so the description must carry the load and it does: file_path is clarified as relative to project root, and change_id is clarified as a hunk ID like "h1"/"h2" or a line number. The format examples add meaning the schema lacks, though edge cases (line number vs hunk ID precedence) are unstated.

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 ("Approves a single granular change (hunk) in a file") and the scope word "single" plus "hunk" cleanly separates it from approve_file_changes, approve_all_files, and reject_change. An agent can pick the right sibling 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?

The "When to use" line gives an explicit condition: one specific change approved while other changes need inspection or rejection. It implies but does not name the alternatives (reject_change, approve_file_changes), so the routing guidance is clear but not fully explicit.

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

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

Beyond the destructive annotation, the description explains exactly what is destroyed: the backup is discarded, the journal entry is cleared, and modifications remain permanently on disk. This gives an agent the side-effect information needed before invoking 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?

The description is well structured and front-loaded with what it does, when to use it, and side effects. It contains some repetition, such as restating that the journal entry is removed and including a return line despite the output 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 single-parameter destructive tool, the description covers purpose, prerequisites, alternatives, side effects, parameter format, and return behavior. An agent has enough context to decide when to call it and what the consequences will be.

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

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

The schema has 0% parameter description coverage, but the description compensates by specifying that file_path is relative to the project root and provides concrete examples. This adds meaningful syntax guidance beyond the bare string parameter.

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: it approves pending changes for a specific file. It also distinguishes this from approve_all_files, making the scope clear without needing 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 a clear prerequisite: inspect via get_file_diff and verify correctness before approving. It also names approve_all_files as the alternative for approving all files, but the exclusion 'File must be modified' is ambiguously worded.

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 and idempotentHint=true, so the safety profile is known; the description earns credit for adding the concrete deletion set and, crucially, the protected artifacts it will not touch. It does not disclose irreversibility or whether files are moved to a trash/backup before removal, and the word 'safely' slightly undersells the destructive hint without contradicting it.

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 the exclusion clause immediately after the inclusion list — every clause carries unique information and nothing is repeated from annotations or 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?

Output schema exists, so return values need not be explained, and given zero parameters the description is nearly sufficient. The remaining gap is that it never says where these files live (workspace root? project directory?), which matters for a destructive cleanup invoked across a multi-project workspace.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a no-argument invocation with fixed, predetermined targets.

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 ('cleans') and enumerates the exact resources removed with literal file patterns (.composebridge-state, .composebridge-journal.json, *.tmp). It also bounds the scope negatively ('without touching source code or .bridge.bak backups'), so an agent knows precisely what is and is not deleted. No sibling tool overlaps with cache cleanup, so sibling differentiation is not a gap here.

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 only implied by the scope statement — an agent can infer this is a housekeeping/cleanup action, but there is no explicit when-to-use guidance or prerequisite mention (e.g. whether it should follow a build or sync). No alternative tool is named as a substitute or as a complement.

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 adds that results include detected patterns, occurrences, and suggestions, which hints at scan-plus-recommendation behavior. It doesn't say how patterns are grouped, whether occurrences reference file/line locations, or how the suggestions should be acted on, so the added value is modest.

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 an illustrative example, then clean Args/Returns sections — no filler sentences. The example line is worth its space because the tool name alone would not convey the target pattern shape. Slightly terse overall, but nothing to cut.

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?

An output schema exists, so return values needn't be spelled out, and annotations cover safety; the description just needs purpose and the filter. It is complete for a single-optional-param analysis tool, with the main residual gap being the absence of any workflow guidance about when a conditional-variant scan is the right move.

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 0% for the single parameter, so the description carries the burden and does at least say it is optional and filters by 'base token name'. It does not clarify matching semantics (exact vs. prefix vs. case-sensitive) or what happens when omitted beyond the word 'optional', leaving real ambiguity for the agent.

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 concrete verb ('Detect') plus a resource ('repeated patterns') and immediately grounds it with a code example of the target shape (a conditional color expression). An agent can tell this is a read-only analysis sweep for conditional token variants. It doesn't explicitly differentiate itself from nearby analysis siblings such as suggest_token_split or analyze_design_scatter, which keeps it out of 5 territory.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The Args section explains the filter but never says when to run a filtered scan versus a full scan, or how this relates to suggest_token_split / replace_pattern in the workflow.

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 safety is covered. The description adds two genuinely useful behavioral facts beyond that: matching is EXACT (no fuzzy or nearest-color fallback) and the result may be plural ('token(s)'), so the caller should expect zero-to-many matches rather than a single object.

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?

One short sentence, front-loaded with the 'Reverse lookup' framing and then the concrete constraint, with no filler or redundant restatement of the tool name.

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 an output schema present and only one required parameter, the description does not need to explain return shape, and it correctly signals exactness and possible multiplicity. However, for a color-input tool the absence of hex format guidance (prefix, digit count, casing) is the one gap that could cause a failed or empty call.

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 0% and the single hex_color parameter has only a title, so the description must carry the format burden. It does confirm the value is a hex color and that matching is exact, but it omits the concrete format details an agent needs: leading '#', 3- vs 6-digit forms, alpha channel support, and case sensitivity.

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-plus-resource ('Find token(s)') and frames it as a 'Reverse lookup' on an exact hex color, which clearly separates it from forward-looking siblings like add_token, set_token, or get_token_siblings. It stops short of naming an adjacent search/list tool (e.g. list_tokens) that an agent might otherwise confuse it with.

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 rather than stated: the agent can infer this is the tool for 'I have a color, what token is it?' and that it is not for listing or editing tokens. There is no explicit when-not guidance, no mention of alternatives when the color is not an exact match, and no note on what to do if nothing is found.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, and the description largely restates this ('Read-only', 'Side effects: Read-only. No files modified'), which earns no extra credit. The one genuine addition is the derivation rule — groups come from object declarations in AppStrings/DesignSystem — which explains what 'group' means and why the set is unfiltered, but no mention of ordering, scale limits, or whether results can be stale.

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?

Well front-loaded with the key fact ('Returns ALL semantic token groups') in the first line and cleanly sectioned by what/when/when-not/returns. The only waste is the triple restatement of read-only behavior ('Read-only' lead, the 'Side effects' line, and the annotations themselves), which could be collapsed to one clause.

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

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

For a zero-parameter, annotated, output-schema-backed read tool, the description covers purpose, scope ('ALL', unfiltered), group derivation, exclusion against list_tokens, and a return summary. Nothing an agent needs to decide or invoke 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?

The tool takes zero parameters, which is the baseline-4 case; the description confirms 'Parameters: None' and does not mislead about any implicit filtering. No further parameter meaning is needed or possible.

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: 'Returns ALL semantic token groups in the project', and grounds the concept with concrete examples ('Actions', 'Dashboard', 'Settings'). It also distinguishes itself from the closest sibling by naming list_tokens as the per-token alternative, 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?

Explicitly gives a when-to-use ('inspect the high-level semantic grouping of design tokens') and a when-NOT-to-use that names the alternative tool (list_tokens for individual tokens). The selection rule between the two siblings is fully specified, leaving nothing 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the 'Side effects: None (strictly read-only...)' section largely restates structured data. The genuinely additive fact is that mappings come from the .composebridge/config.json file, which is modest added context.

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?

Well front-loaded: one-line purpose followed by clearly labeled when-to-use, when-not-to-use, and side-effect sections. There is mild redundancy in repeating the read-only guarantee and in an Args line that echoes the schema, but no wasted prose.

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 read tool with rich annotations and an output schema, the description covers purpose, alternatives, and safety adequately. The only meaningful gap is the fallback behavior when project_root is not supplied.

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

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

The single parameter has 0% schema description coverage, so the description must compensate, but it only offers 'project_root: Optional path to project root,' which essentially restates the parameter's title and null default. It does not say what happens when omitted (e.g., whether the current working directory or an auto-detected root is used).

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 ('Returns current design/registry file mappings') plus the source of truth ('.composebridge/config.json'), so an agent can distinguish it from set_design_file_mapping and list_tokens 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?

Provides explicit 'When to use' conditions (before modifying design tokens, when debugging token resolution) and explicit 'When NOT to use' exclusions that name the correct alternative siblings for each case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds the concrete mechanism (diffing the .bridge.bak backup against on-disk content) and a 'no files modified' side-effect statement. The 'Read-only' lines duplicate the annotation, so the value beyond structured fields is solid but partly redundant.

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 one-line purpose, then organized into labeled sections (What it does / When to use / When NOT / Side effects / Parameters / Returns). Slightly redundant in repeating 'Read-only' in both the opening and the side-effects line, but every section 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?

A single-parameter read tool whose description covers purpose, workflow positioning, path semantics, side effects, and return shape; an output schema also exists, so return values need not be detailed further. Nothing an agent needs 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 description coverage is 0%, so the description carries the full burden and does so: file_path is defined as relative to project root, with concrete example paths including a nested 'ui/theme/AppStrings.kt'. It also ties the parameter to entries returned by list_modified_files, which adds meaning the schema lacks.

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: returns before/after content plus a unified diff for a specific modified file, and explains how the diff is computed (.bridge.bak backup vs current on-disk content). This clearly separates it from sibling read tools like list_modified_files and from the approve/reject mutators.

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 when to use (inspect exact changes before approving or rejecting), when not to use (call list_modified_files first to obtain valid paths), and names the sibling tools approve_file_changes and reject_file_changes as the downstream actions. No 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?

Annotations already declare readOnly/destructive/idempotent hints, so the 'strictly read-only' line is mostly redundant. The description nonetheless adds real behavioral value the annotations cannot: that this is a polling endpoint, that job_id is a background handle, and the status state machine (queued|running|completed|failed).

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 purpose followed by labeled sections, which is easy to scan. A few lines (the 'Side effects: None' note, the Args/Returns headers) repeat structured data or boilerplate and could be trimmed without losing meaning.

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

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

For a single-parameter read tool this covers everything an agent needs: purpose, invocation condition, exclusion, argument provenance, and the shape and enumeration of the response. No output schema is required to disambiguate the return value.

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 0% — job_id is an undocumented string — so the description carries the burden, and it does: it identifies job_id as the ID returned by run_gradle_build, which tells the agent where to obtain the value. The expected format of the ID itself is still unspecified.

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 ('Check the status and result of a Gradle build job') and ties it to the sibling that produces the job, so an agent can separate it from run_gradle_build or list_allowed_gradle_tasks 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?

Explicit 'When to use' (polling background status returned by run_gradle_build) and 'When NOT to use' (no Gradle job started) sections, naming the related tool directly. Nothing is left 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?

Beyond the read-only and idempotent annotations, it discloses that results are real-time, come directly from the IDE, and do not trigger Gradle. It still omits operational details such as whether an IDE must be open or connected and what happens when the timeout expires or diagnostics are unavailable.

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 single sentence is front-loaded with the action and diagnostic types, then adds the useful IDE-source and no-Gradle constraints. There is no filler or redundant restatement of the tool name.

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 output schema removes the need to describe return fields, and the core operation is clear enough for a basic read-only call. Completeness is limited by undocumented optional parameters, missing IDE availability and failure behavior, and no explicit boundary with scan_project_diagnostics.

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 0%, and the description does not explain any of the three parameters. In particular, it never states that file_path optionally limits scope, how timeout_seconds affects the IDE request, or that include_warnings controls whether warnings accompany the reported errors.

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: fetching compilation, unresolved-reference, and syntax errors from Android Studio or IntelliJ. "Without running Gradle" distinguishes it from build-based diagnostics, but it does not clearly differentiate the closer sibling scan_project_diagnostics.

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 wording supplies a clear use case: obtain current IDE-reported errors while avoiding a Gradle build. It does not explicitly say when to prefer scan_project_diagnostics or run_gradle_build, nor when file_path should be used to narrow the request.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Read-only analysis' and 'Side effects: Read-only. No files modified.' largely restate structured data. The description does add some value by naming the return payload fields (detected style, confidence score, examples, recommendations) and the fact that analysis is heuristic rather than exhaustive, but it discloses nothing about permissions, cost, or how confidence is derived.

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 labeled sections (What it does / When to use / When NOT to use / Side effects / Parameters / Returns) make it scannable and front-loaded. But the opening line and the 'What it does' line say the same thing, and the read-only guarantee appears three times, so several sentences do not earn their 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 single-optional-parameter read tool this covers usage, alternatives, accepted parameter values, and the shape of the result. An output schema exists, so the Returns section is a bonus rather than a necessity, and the only remaining soft spot is that 'dimension' as a token type is never defined.

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 0% and the schema has no enum, so the description is doing real work by enumerating the accepted values 'dimension' (default) and 'color'. It does not explain what distinguishes a dimension token from a color token, which would have fully closed the gap.

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: detects camelCase, snake_case, or PascalCase usage across project tokens. It also carves out a clear boundary against list_tokens, so an agent can distinguish it from the sibling that inspects token values 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?

Explicit when-to-use: call before add_token or replace_pattern to keep new tokens consistent with the existing style. Explicit when-not-to-use: do not use it to read token values, use list_tokens instead. Both the positive and negative routing conditions are stated.

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

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

The "Side effects: None (strictly read-only)" line largely restates readOnlyHint and destructiveHint=false, which annotations already declare. What it adds beyond the annotations is the set of state fields surfaced (agent_busy, queue_count, snapshot_version) and the operational timing hint for batch runs.

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 one-line purpose followed by labeled When to use / When NOT / Side effects blocks, easy to scan. The side-effects bullet is partly redundant with the annotations, a small amount of wasted text.

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

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

A zero-parameter read tool with an output schema and full annotation coverage needs little more; the description supplies purpose, timing guidance, and the alternative tool. Return-value formatting can be delegated to the output schema.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The named state fields describe returned data rather than inputs, which is harmless but not a schema contribution.

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

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

States a specific verb and resource ("Get the current sync status") and scopes it to the Bridge Server, and the When NOT section names the sibling trigger_user_sync so the agent can differentiate 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?

Explicit when-to-use (inspect agent_busy, queue_count, snapshot_version before batch operations) plus an explicit when-not-to-use routing to trigger_user_sync for applying changes. Nothing is left 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 readOnlyHint, destructiveHint=false, and idempotentHint, so the 'Side effects: None (strictly read-only)' line is largely redundant. Beyond that, the description adds genuine behavioral context about the shape of the result — per-usage file:line locations and enclosing composables — which the annotations do not cover.

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 labeled sections make it scannable and front-loaded, but there is waste: the closing line 'Use this BEFORE changing a token to understand the impact' repeats the 'When to use' bullet verbatim in substance, and 'Side effects: None' restates the annotations. Trimming those two items would make the definition tighter.

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 read-only analysis tool with an output schema already present, the definition covers purpose, timing, exclusions, parameter examples, and result contents, so an agent can invoke it correctly without guessing. The 'Returns: JSON with full impact analysis' line adds nothing beyond the output schema, but the overall coverage is 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 0%, so the description must carry the burden, and it does: it gives concrete example values for token_name ('welcomeCardHeight' or 'Primary') and clarifies that project_path is an optional explicit project root. That said, it does not explain token_name semantics such as whether it accepts a key, a display name, or a dotted path.

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 plus resource ('Get impact analysis for a specific token') and enumerates exactly what the analysis contains (file:line usages, enclosing @Composable, total affected UI elements). It is clearly distinct from data-mutation siblings like set_token or rollback_last, though it never names an alternative tool explicitly.

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

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

Provides explicit 'When to use' ('Call BEFORE modifying or deleting a token') and 'When NOT to use' sections, plus a restated precondition. The agent knows exactly when this tool is the right choice and when to skip it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, making the repeated 'Read-only' and 'No files modified' statements redundant. The description still adds useful behavioral context by specifying that the original token is excluded and that an empty list is returned when no siblings 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?

The description is sectioned, front-loaded, and easy to scan, with only minor redundancy such as repeating read-only behavior twice and including a return-value summary despite an output schema. Most sentences earn their place.

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

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

Given a single-parameter read-only tool with rich annotations and an output schema, the description covers purpose, usage conditions, exclusions, parameter format, and return behavior. An agent has everything needed to call it 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 0%, so the description must carry parameter meaning. It does this well by explaining that token_name accepts either an exact name like 'Primary' or a fully-qualified name like 'AppColors.Primary', adding format detail beyond the bare string 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 and resource ('Returns semantically related tokens') with a concrete example (Primary → PrimaryDark, PrimaryLight) and distinguishes the result from the original token. An agent can understand the tool's unique function 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 when-to-use ('exploring related tokens or checking which color variants already exist') and when-not-to-use guidance (no original token, empty list if none exist). It does not name sibling alternatives such as list_tokens or find_token_by_color, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the 'side effects: none' line largely restates structured data. However, the description adds the meaningful concept of a whitelist policy that governs what can be executed, which is context not present in the annotations.

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

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

Front-loaded purpose followed by clearly labeled when/when-not/side-effects sections; every line carries actionable routing or behavioral information with 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?

An output schema exists, so return values need not be described, and a zero-parameter read-only tool needs no further prerequisites. Nothing an agent needs to select and 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description contradicts or misleads about inputs.

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 sentence states a specific verb (list) and resource (Gradle tasks) and immediately ties it to a scope ('that can be run via run_gradle_build'). This distinguishes it clearly from the sibling run_gradle_build without requiring the schema to be opened.

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 both the when-to-use condition ('check which Gradle tasks are whitelisted') and the when-not-to-use case with the alternative tool named ('use run_gradle_build instead'). No inference is required to route between the two.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety behavior is well covered. The description adds that this is a strictly read-only journal lookup and that it returns rollback-eligible patterns, though the side-effects sentence largely repeats annotation information.

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 short and front-loaded, with clear sections for purpose, when to use, when not to use, and side effects. Every sentence supports correct tool selection or invocation.

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

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

Given the empty parameter schema, rich annotations, output schema, and nearby rollback tools, the description supplies everything needed for selection and invocation. Return-value details can be delegated to the output schema.

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

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

There are zero parameters, so the baseline is 4. The description adds no parameter detail, but none is needed because the schema has no parameters.

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

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

The description uses a specific verb-resource pair, 'List all applied patterns,' and qualifies scope as patterns that can be rolled back. It explicitly distinguishes this from rollback_pattern, so an agent can identify the tool without opening sibling 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?

It gives explicit when-to-use cases: inspecting refactoring history and retrieving valid pattern_ids for rollback_pattern. It also gives an explicit when-not-to-use case and names the correct alternative, rollback_pattern.

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, so the safety profile is covered, but the description adds genuinely new behavior: results come from the session journal rather than git status and do not survive session boundaries. Minor credit lost for restating 'Read-only. No files modified.' twice, which duplicates readOnlyHint.

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?

Labeled sections are front-loaded and scannable, with the scoping caveat appearing before the tool is ever called. The only waste is the duplicated read-only statement in the opening line and the 'Side effects' section.

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 no-argument, read-only list tool this covers purpose, usage boundary, session lifetime, source of truth, and return shape. Nothing an agent needs in order to select or call it 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?

Zero parameters, so the baseline is 4; 'Parameters: None.' is consistent with the empty schema and prevents an agent from looking for filter arguments. Nothing further is needed or possible here.

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 ('Lists files modified by recent replace_pattern operations') plus the scoping qualifier 'in the current session'. That scope detail distinguishes it from the git-oriented sibling get_file_diff without the agent needing to open 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?

Contains explicit 'When to use' (reviewing unapproved changes before approve/reject) and 'When NOT to use' (cross-session persistence; git-based diffs → get_file_diff). It names the alternative and the condition that selects it, which is exactly what routing requires among 30+ 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=true, idempotentHint=true and destructiveHint=false, so the 'None (strictly read-only)' side-effects note largely restates structured data. It does add useful context beyond annotations: that removal must be done manually or approved, and that output is JSON with token 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?

Sectioned and front-loaded with the core statement first, so the important part is immediately visible. A few lines do not earn their place, notably the filler sentence 'Orphan tokens are a sign of design system clutter' and a redundant 'Returns' block given an output schema exists.

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 read-only listing tool, everything an agent needs is present: what the tool returns, when to use it, its non-destructive nature, and the caveat that it cannot remove anything. Output schema and annotations fill the remaining 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 coverage is 0% and the single project_path parameter has no schema description, so the description must carry the load. 'optional — explicit path to project root' conveys optionality and intent, but leaves unstated what happens when omitted (implicit project discovery), so it only partially compensates.

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 ('List all orphan tokens') and immediately defines the filter in a parenthetical ('registered but never used'), which distinguishes it semantically from the sibling list_tokens. An agent can tell exactly what set of tokens it will get back.

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?

Explicit 'When to use' (design system cleanup, dead code elimination) and 'When NOT to use' (do not expect it to delete tokens) sections give clear context and one exclusion. It stops short of naming a concrete alternative sibling (e.g. list_tokens for all tokens), which would be the 5-level detail.

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, and destructiveHint=false, so the safety profile is covered; the description's "strictly read-only" line is largely redundant. What it does add of value is the shape of the result set — naming duplicate and orphan detection alongside registered and hardcoded values — which tells the agent this is an audit-style sweep rather than a simple enumeration.

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 core action, then organized under clear labeled sections, so an agent can scan it quickly. The "Side effects: None" line duplicates the annotations and slightly dilutes an otherwise tight definition.

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 read tool with a full annotation set and an output schema, this covers purpose, return categories, exclusions, and the sole parameter. Nothing needed to invoke it correctly is missing; the only omission, default path resolution, is minor and inferable.

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 0% and the schema only says the single property is a string, so the description's "optional — explicit path to project root" materially adds both optionality and meaning. It stops short of explaining what happens when project_path is omitted (presumably auto-detection), leaving one small gap.

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 ("List all design tokens in the project") and enumerates exactly what the listing comprises: registered tokens, hardcoded literals, duplicates, and orphans. It is clearly separable from siblings like find_token_by_color, set_token, and add_token, which are named explicitly.

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 dedicated "When to use" and "When NOT to use" sections, and routes the agent to the correct alternative in each exclusion case (find_token_by_color for reverse lookup, set_token/add_token for edits). This is explicit when/when-not plus alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes further: it discloses the .bridge.bak byte-level backup mechanism, states that modified files are overwritten and the journal is cleared, and warns that rollbacks may fail (pointing to the force variant). That is material behavioral context beyond what the annotations carry.

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 destructive warning and organized into labeled sections (What it does, When to use, When NOT, Side effects, Returns), which makes scanning fast. Minor redundancy: the Returns section restates what an output schema already covers, and 'Parameters: None.' is padding, but neither obscures the essentials.

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

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

For a zero-parameter destructive rollback, the description covers purpose, exclusions, side effects, backup mechanism, journal clearing, and the failure caveat. Nothing an agent needs in order to decide whether to call this or its siblings 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?

The tool takes zero parameters, so there is nothing to disambiguate and the schema is trivially complete; the description's 'Parameters: None.' is consistent with that. No extra meaning is needed or possible here, capping the realistic value at the baseline.

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

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

Names a specific verb and scope: rolls back byte-for-byte all files modified in the current journal session. Together with the name and the explicit 'Destructive:' lead-in, an agent can distinguish this bulk rollback from single-file or force variants without reading 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 ('completely discard all recent changes') and when-not-to-use with named alternatives: reject_file_changes for a single file and reject_all_files_force when rollbacks may fail. Both exclusions and the sibling routing are spelled out rather than implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the crucial nuance beyond that: the journal is cleared even if some rollbacks fail, and files may be left inconsistent. That is exactly the consequence an agent needs before choosing the forceful path over the safe one.

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 header structure (what/when/when-not/side effects/returns) is front-loaded and scannable, with the destructive warning first. There is minor redundancy between the opening 'Destructive + Forceful' line, the 'What it does' sentence, and the 'Side effects' line restating the same unconditional-clear behavior.

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

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

For a zero-parameter destructive tool, the description covers the decision criteria, the risk, and the fallback, and an output schema already exists so return details need not be expanded. Nothing an agent needs to invoke this 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?

There are zero parameters, so there is no semantics to convey; the description's 'Parameters: None.' correctly confirms this. Baseline for a no-parameter tool applies, with no added meaning possible.

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 ('forcefully attempts rollback and clears the journal unconditionally') and immediately contrasts it with the non-force sibling reject_all_files. An agent can distinguish it from approve_all_files and reject_all_files 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 explicitly states the trigger condition ('only when reject_all_files fails due to missing backups or file corruption') and names the safe alternative to use otherwise. Both the when and the when-not are spelled out with the specific failure mode that selects this tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description adds real value by scoping the destruction to only the specified hunk and by stating it restores the baseline on disk. It doesn't mention whether the action can be undone or that the file must currently be in a modified state, which would be the remaining useful context.

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?

Labeled sections (What it does / When to use / Parameters / Returns) make it scannable and the core action is front-loaded in the first sentence. The headers are slightly heavy for a two-parameter tool but every line 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 destructive single-hunk mutation with two required params and an output schema, the definition covers purpose, selection criteria, parameter formats, and result shape. The only gap is recovery/undo behavior and any precondition about the file being modified, which matters given the destructive hint.

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 0%, so the description carries the full burden, and it does compensate well: file_path is anchored to "relative path to project root" and change_id accepts either a hunk ID with concrete examples ("h1", "h2") or a line number. The ambiguity of how a bare line number resolves to a hunk is left unexplained, keeping it from 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 states a specific verb and resource ("Reverts a single granular change (hunk) in a file") plus a scope qualifier ("while keeping other changes intact"). That granularity implicitly but clearly distinguishes it from sibling tools like reject_file_changes and reject_all_files, which operate at file or batch level.

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 "When to use" line gives a clear selection condition: one unwanted change while keeping others in the same file. It stops short of naming the alternative (reject_file_changes) explicitly for the case where all changes should go, so it falls shy 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?

Goes well beyond the annotations: annotations only say destructiveHint=true, while the description discloses that it restores byte-for-byte from a .bridge.bak backup, overwrites the file, and removes the entry from the journal, plus the precondition that the file must currently be modified. The gap is the undocumented `force` parameter, which plausibly bypasses that precondition and is never explained.

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?

Labeled sections (What it does / When to use / When NOT / Side effects / Parameters / Returns) make it scannable and front-load the destructive warning. Slightly verbose, and the Returns line is redundant given an output schema exists, but nothing is 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 destructive, journal-backed rollback tool it covers mechanism, precondition, and side effects thoroughly, and the return value is covered by the output schema so it needn't be expanded. The only real hole is the unexplained `force` flag, which matters given the tool's destructive nature.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it documents only file_path (with a relative-path rule and two concrete examples). The second parameter, `force`, is never mentioned, leaving an agent with no idea what it changes about the destructive behavior.

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 ("Reverts pending changes for a SINGLE file") and immediately names the mechanism (.bridge.bak backup), which distinguishes it from the sibling reject_all_files and from approve_file_changes. The "SINGLE file" emphasis paired with the explicit alternative makes it unambiguous which tool to pick.

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

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

Provides explicit "When to use" (modifications are incorrect and need discarding) and "When NOT to use" (file must be currently modified; use reject_all_files for all files), naming the alternative sibling directly. This is the textbook when/when-not/alternative structure.

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 and readOnlyHint=false, but the description goes further: it discloses that multiple .kt files are modified simultaneously, that a new token is created, that changes are recorded in the journal, and that rollback is available through rollback_pattern(pattern_id). That is meaningful behavior beyond the annotation flags and beyond a bare 'destructive' signal.

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 destructive warning and organized under labelled sections, which suits a risky batch operation. There is mild redundancy in flagging DESTRUCTIVE twice (header and Side effects) and 'When NOT to use' is really a 'how to mitigate' instruction rather than an exclusion, 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 destructive, multi-file mutation with two parameters, the definition covers mechanism, prerequisites, mitigation, side effects, and recovery. An output schema exists and the description still summarizes the return payload (replacements, modified files, created token name), leaving no material gap.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: pattern_id is tied to its required source tool, and dry_run is explained as a preview that writes nothing to disk, with a recommendation to run it first. Both parameters gain meaning they do not have in the bare 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 and resource with explicit scope: 'Replaces ALL occurrences of a pattern across the project,' plus the mechanism 'Creates new token + replaces usages.' This clearly separates it from siblings such as set_token, set_text, and detect_conditional_variants, which an agent could otherwise confuse with a replacement operation.

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

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

Provides explicit 'When to use' (recurring conditional or hardcoded pattern across all files) and 'When NOT to use' guidance that routes the agent to dry_run=True first. It also imposes an upstream dependency, stating pattern_id must come from detect_conditional_variants, and names rollback_pattern as the undo 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is known. The description adds useful scoping — it destroys exactly one edit, the most recent, and only within the current session. It does not say what happens when there is nothing to roll back, whether repeated calls walk further back through history, or whether the rollback is itself reversible.

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 with zero filler, and the two load-bearing constraints (LAST, current session) are front-loaded where the agent will see them. Nothing is repeated from the schema or annotations.

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

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

The tool is simple, has no parameters, and has an output schema so return values need no prose. What is missing is disambiguation from rollback_pattern and any statement about behavior at the boundaries (empty history, repeated invocation), which matters for a destructive operation that is explicitly non-idempotent.

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

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

The tool takes zero parameters, so per the baseline this scores 4. The description correctly adds no parameter discussion, and the choice to take no arguments is consistent with 'LAST edit' semantics.

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 target: 'Reverts the LAST surgical edit made in the current session.' The scope qualifiers (LAST, current session) make the operation concrete. It does not, however, distinguish itself from the sibling rollback_pattern, which also sounds like a revert operation, so an agent must guess which one applies.

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 'LAST ... in the current session' implies when this is appropriate (undo the most recent edit), but there is no explicit when-to-use statement, no exclusion, and no mention of rollback_pattern as the alternative for pattern-level reverts. Usage is inferable but not guided.

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 and readOnlyHint=false, so the safety profile is known, but the description adds real context: files are reverted byte-for-byte to pre-replacement state, and the rollback cannot succeed if files were modified externally. It also names the provenance requirement (pattern_id from the original replace_pattern response). It does not mention partial-failure behavior or whether the rollback is atomic across files.

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 same content is delivered twice: a structured block (What it does / When to use / When NOT to use / Side effects) followed by a near-identical prose repetition of every one of those points. Roughly half the text is redundant, which inflates length without adding information and risks the agent treating the duplicate lines as distinct constraints.

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 purpose, usage, prerequisites, destructive side effects, and the parameter source, which is everything an agent needs to invoke it correctly; an output schema exists so return details need not be spelled out (the description restates them anyway). Minor gap: no guidance on what state the workspace is left in if only some files can be reverted.

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 0% and the single parameter has no schema description, so the description must carry the burden — and it does, specifying that pattern_id must be the exact value returned by the original replace_pattern response. That provenance detail is meaningfully beyond the bare 'string' type in the schema.

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

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

States a specific verb (rolls back) and a specific resource scope (ALL changes made by a specific replace_pattern call), including the 'ALL' quantifier that separates it from single-edit undo. An agent can distinguish it from rollback_last and reject_change 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?

Provides explicit 'When to use' (unexpected UI behavior, compilation issues, undoing by pattern_id) and 'When NOT to use' (single token edits -> rollback_last or reject_change; no valid pattern_id -> list_applied_patterns) sections. Alternatives and the condition selecting each are named outright.

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?

Goes well beyond the annotations: discloses that the build runs in the background, that it writes artifacts to build/ directories, that tasks are whitelist-restricted, and that async mode returns a job_id for polling with get_gradle_status. This explains why readOnlyHint=false without contradicting destructiveHint=false, since artifacts are build output rather than user data.

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?

Well front-loaded and sectioned (When to use / When NOT to use / Side effects / Args / Returns), so an agent can scan quickly. Slight redundancy: the paragraph 'This lets the agent verify that code changes compile…' restates the when-to-use bullets, and the Args/Returns text duplicates the input and output schemas.

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 non-readonly build-invocation tool with an output schema present, the description covers side effects, async lifecycle, and the follow-up tool. The only omission is a concrete pointer for discovering the full task whitelist, which would be useful given the incomplete enumeration.

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 0%, so the description carries the load and does document all three parameters: task with whitelist enforcement and example values, timeout_seconds with a 5-minute default, and async_mode with its default and downstream polling behavior. The whitelist list is left as 'etc.' and does not point to the sibling list_allowed_gradle_tasks, which would have closed the remaining gap.

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 ('Run a Gradle task') plus the differentiating trait 'with async tracking support'. An agent can distinguish it from get_gradle_status (polling) and list_allowed_gradle_tasks (enumeration) 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?

Explicit when-to-use bullets (verify surgical edits compile, run after batch changes) and explicit when-NOT-to-use bullets that name the alternative tools (check_syntax_cli, ast_finder) for the cases this tool does not cover. The alternative-routing 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context: the scan is sequential, static (no Gradle invocation), and project-wide, which hints at cost. It stops short of saying how expensive a full scan is or how partial results are signalled when bounds are hit.

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 well-formed sentence with the scope and the key differentiator ('without running Gradle') front-loaded. No filler, though it is arguably too terse given three undocumented parameters.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The gap is the input side: three tunable parameters including a timeout and a file cap that govern runtime behavior are left entirely undocumented for what is potentially an expensive project-wide scan.

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 0% and none of the three parameters (max_files, timeout_seconds, include_warnings) are explained in the description. Worse, the prose says it collects 'technical debt warnings' while include_warnings defaults to false, leaving the agent to guess at the interaction.

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 ('Sequentially scans all Kotlin files in the project workspace') plus the outputs collected ('compilation errors and technical debt warnings'). The phrase 'without running Gradle' implicitly separates it from run_gradle_build, but no sibling is named explicitly.

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 'without running Gradle' clause implies this is a lightweight alternative to a Gradle build, which gives an agent a usable cue. However, it never states when to prefer this over get_ide_diagnostics or run_gradle_build, and gives no exclusions or prerequisites.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered; the description still adds the concrete side effect that .composebridge/config.json is modified on disk. It does not state whether an existing mapping for the same token_type is silently overwritten, which is the main remaining behavioral 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 purpose sentence is front-loaded, and the labeled sections make scanning fast. The Args block repeats some of the schema, but given the zero coverage that repetition is functional rather than waste.

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

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

For a destructive config-mutating tool the description covers trigger, exclusions, alternative, and disk side effect, and an output schema exists to explain return values. Only the overwrite/conflict semantics of re-mapping an already-mapped token type are left 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 0%, so the description must carry the parameter meaning, and it largely does: it supplies the accepted token_type values ('color', 'dimension', 'string', 'all') that the schema does not enumerate, gives a relative-path example for file_path, and marks project_root optional. It stops short of stating path constraints or validation rules for file_path.

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 and resource (sets a design file mapping) and pinpoints the artifact it writes (.composebridge/config.json) for a given token type. An agent can distinguish it from get_design_file_mappings 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?

Provides an explicit 'When to use' section tied to a concrete trigger (NEEDS_MANUAL_MAPPING from ComposeBridge) and a 'When NOT to use' section that names both the excluded condition (standard file locations) and the alternative sibling (get_design_file_mappings).

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 flag destructiveHint=true and readOnlyHint=false, but the description adds the real workflow consequences: writes on disk, requires approve_file_changes to land in git, and is revertible via reject_file_changes. It also discloses non-obvious auto-migration side effects. It does not mention scope of the edit when file_path is omitted, 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?

Labeled sections (What it does / When to use / When NOT / Side effects / Parameters / Returns) make it scannable and front-loaded with the DESTRUCTIVE warning. Minor redundancy: 'Modifies .kt files' appears twice in the first three lines.

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?

Output schema exists, yet the returns line still usefully names success status, old_text, new_text, and file location. The one real gap is that file_path is optional but the description never says what happens when it is omitted (search scope across files), which matters for a destructive edit.

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 0%, so the description carries the full burden and does: token_name is explained as either a reference key or literal old text, new_value as the replacement, file_path with path examples, and line as an optional disambiguator for repeated text. The dual-mode token_name semantics are otherwise undiscoverable.

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 ('Surgically edit text content', 'Modifies .kt files') plus the automatic BridgeTextRegistry wrapping behavior. It clearly distinguishes itself from the token-oriented siblings by declaring text strings as its domain.

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 to use' covering both AppStrings-defined and hardcoded Text("...") cases, and an explicit 'When NOT to use' routing colors/dimensions to set_token or add_token. This is exactly the routing an agent needs against a large sibling set.

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, but the description goes well beyond them: it discloses that source code on disk changes, that a WebSocket live preview is pushed to the phone, and that approve_file_changes must commit or reject_file_changes must revert. That approval-workflow dependency is exactly the kind of context annotations cannot convey.

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?

Labeled sections (What it does / When to use / When NOT to use / Side effects / Parameters / Returns) make it scannable and front-loaded. Minor redundancy: 'DESTRUCTIVE: Modifies .kt files' appears in the opening line and again under side effects, and the returns section partially duplicates the output 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 destructive, two-parameter mutation tool, the description covers purpose, alternatives, on-disk consequences, the approval gate, and parameter formats. An output schema exists, so the brief Returns note is supplementary rather than the sole source of return-shape information, leaving no meaningful gap.

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

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

Schema description coverage is 0% and both properties are bare strings, so the description carries the full burden. It supplies accepted formats and examples for each: token_name as either 'Primary' or 'AppColors.TokenName', and value as '#RRGGBB' or a numeric dimension like '24.dp'. This fully compensates for the empty 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 and resource ('Surgically edit a design token value in source code') and immediately scopes it to .kt files containing the token definition. It explicitly names the siblings it is not (set_text, add_token), so an agent can disambiguate 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?

Provides an explicit 'When to use' condition (adjusting a color or dimension with immediate visual feedback) and a 'When NOT to use' section that routes text edits to set_text and hardcoded-value conversion to add_token. Both alternatives are named with the condition that selects them.

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, and destructiveHint=false, so 'Read-only. No files modified' largely repeats structured data (twice, in the lead line and the Side effects line). The description does add one piece of behavior beyond annotations: the sequencing constraint that this must run before replace_pattern. No mention of cost, scope limits, or confidence of suggestions.

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?

Well-structured with labeled sections, front-loaded with the key constraint. The 'Read-only' claim appears in both the opening line and the Side effects field, and the Returns section duplicates the output schema, so a little space 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 two-optional-parameter read-only analysis tool, the description covers purpose, preconditions, exclusions, parameter meaning, and output shape. Nothing an agent needs in order 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 description coverage is 0%, so the description must compensate; it does describe both parameters' purpose ('optional filter to analyze a specific token only', 'optional override for project root path'), which is meaningful. However, it adds no format or syntax detail (e.g. expected path shape or token name convention) that the bare schema lacks, so it only partly fills the gap.

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 ('suggests splitting tokens used in multiple contexts') plus a concrete detection criterion ('cards and buttons'). The explanation of 'what it does' makes it clearly distinguishable from generic token-editing 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?

Explicitly says to use it BEFORE replace_pattern, and names two exclusions with the correct alternatives (get_token_impact for impact analysis, get_token_siblings for sibling tokens). An agent needs no inference to route correctly.

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 description's added value is the precondition (only works when the AI agent is not busy) and the disclosure that on-disk source files are mutated. It stops short of saying whether a failed run leaves partial edits, which matters for a non-idempotent 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?

The labelled structure (when to use / when not to use / side effects) is scannable and front-loaded with the core action. There is mild redundancy in restating 'applies all queued edits (dimension + color)' a second time and in the Returns block, which duplicates the output 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 zero-parameter, non-idempotent, destructive tool the description covers intent, precondition, side effect and result shape, and an output schema plus annotations carry the rest. The remaining gap is recovery guidance – nothing points at rollback_last if applied edits turn out to be wrong.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate – the baseline applies. The only semantic detail given, that the queued edits cover dimensions and colors, is useful framing but not a parameter concern.

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 concrete operation (trigger user_sync on the Bridge Server) and states its effect: applying queued dimension and color edits to source files. That is enough to separate it from siblings such as get_sync_status or approve_file_changes, though those siblings are never named explicitly.

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 (flush and apply pending queued edits from the Android device) and an explicit 'When NOT to use' rule (the agent_busy lock, or the agent actively editing source files). The reader needs no inference to decide whether to call it.

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