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

With no annotations, the description carries the full burden and does disclose key mutation behavior: it adds a definition to AppDimens.kt/AppColors.kt, replaces ONLY the specified line, and touches no other line. It also warns that force_create bypasses duplicate detection. It omits permissions, failure modes, and whether edits enter a pending-approval workflow implied by siblings like approve_file_changes.

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

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

It is front-loaded with purpose, then a tight numbered behavior list, usage note, Args and Returns. The structure is scannable and every section earns its place, though the Returns line adds little 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 7-parameter mutation tool with no annotations, the description covers behavior, all parameters, and a prerequisite step, which is substantial. The main gap is the staged-approval/rollback workflow implied by sibling tools, which is not mentioned.

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 document all parameters, and it does so via a full Args block. It supplies concrete examples ('16.dp', '0xFF7C3AED', 'padding_md') and enumerates the token_type values ('dimension' or 'color') that the schema itself 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?

The description opens with a specific verb+resource ('Convert a hardcoded value to a design token') and the numbered steps make the operation concrete. It does not explicitly distinguish itself from the nearby set_token sibling, so it stops short of a 5.

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

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

It gives clear context via the prerequisite 'Use list_tokens() first to find hardcoded values that could become tokens.' However it offers no when-not guidance and never contrasts add_token with set_token, which an agent could reasonably confuse it with.

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

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

With no annotations, the description carries the full burden and delivers: permanent approval, backup/journal clearing, no rollback, and side-effect scope across all modified files. This is exactly the destructive-operation disclosure an agent needs before invoking.

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 destructive warning, then labeled sections that are easy to scan. Slight redundancy between the opening line and 'Side effects', but every statement adds a distinct fact (scope, irreversibility, alternatives).

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-param destructive tool with an output schema present, the description covers purpose, usage, alternatives, side effects, and return confirmation. Nothing an agent needs 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 baseline is 4. The description reinforces this with an explicit 'Parameters: None', leaving no 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 (approves) and resource (all pending files/changes), and the scope 'ALL' plus 'permanently' distinguishes it from the sibling approve_file_changes. An agent can tell exactly what this does from the first line.

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' and 'When NOT to use' sections, with named alternatives (approve_file_changes for single files, reject_all_files to discard). Routing is unambiguous.

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

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

With no annotations, the description carries the full burden and does well: it discloses side effects (journal entry and backup cleared, modifications remain permanently on disk) and implies irreversibility by discarding the backup. It stops short of stating outright that the action cannot be undone or naming any permission/auth requirements, 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?

The labeled sections (What it does / When to use / When NOT to use / Side effects / Parameters / Returns) are front-loaded and scannable, and each carries real information. The Returns section is mildly redundant given an output schema exists, costing it the top score.

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

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

For a mutation tool with no annotations and a fully opaque schema, the description covers the essentials: effect, prerequisites, side effects, irreversibility implication, and parameter format. Only minor gaps remain (explicit non-reversibility, any auth requirements), and the return-value question is already handled by 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?

Schema description coverage is 0% for the single file_path parameter, so the description must compensate. It does: it specifies the path is relative to the project root and gives two concrete examples ('QuickActionsWidget.kt', 'ui/theme/AppStrings.kt'), which is exactly the format guidance the bare string 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 (approves), resource (pending changes), and scope (a SPECIFIC file), plus the mechanical effect of removing the journal entry. It also explicitly contrasts with the sibling approve_all_files, so an agent can distinguish the two without inspecting 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 explicit when-to-use ('when changes to a specific file have been inspected via get_file_diff and verified correct') and when-NOT-to-use guidance, including the prerequisite that the file must be modified and the alternative tool for the all-files case. 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?

No annotations are provided, so the description carries the full behavioral burden. 'Detect' plus the 'Returns: JSON with detected patterns + occurrences + suggestions' line reasonably conveys a read-only, non-mutating analysis, but it says nothing about permissions, scan scope (which files/workspace), or cost/latency. Nothing contradicts expected behavior, but disclosure is thin.

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 verb and an illustrative example, then Args and Returns in clearly labeled blocks with no filler sentences. The code example is long but earns its place by disambiguating what a 'conditional variant' is.

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 single parameter is explained and an output schema exists, so the Returns line is largely redundant but harmless. What's missing for a detection tool in a dense sibling set (replace_pattern, suggest_token_split, list_applied_patterns) is any statement of where detection fits in the workflow — e.g., that results feed into `replace_pattern`.

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, and it does: it states `token_name` is optional and filters by base token name, which is exactly the semantic the bare schema (`type: string`, `default: null`) lacks. Only a single parameter exists, so this is close to complete, though it doesn't specify matching semantics (exact vs substring).

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 target ('Detect repeated patterns') and anchors it with a concrete code example (`if (isDark) Color(0xFF818CF8) else AppColors.Primary`), so the agent knows exactly what class of finding this produces. It does not, however, explicitly distinguish itself from sibling tools like `suggest_token_split` or `find_token_by_color`, which the agent must infer from the example.

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

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

Usage is implied by the example pattern rather than stated: an agent can infer this is for locating hardcoded conditional color branches that should be tokenized. There is no explicit when-to-use statement, no exclusions, and no named alternative (e.g., when to prefer `suggest_token_split` or `replace_pattern` after detection).

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

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

With no annotations, the description carries the full behavioral burden; it does disclose that matching is on an 'exact' color, ruling out fuzzy/nearest-match behavior, and 'token(s)' signals the result may be plural. It does not state that the operation is read-only or how malformed hex input is handled. Output schema exists, so return-format disclosure is not required.

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 the key qualifier ('reverse lookup', 'exact hex') front-loaded and no wasted words. It is terse to the point of omitting format detail, but structurally sound.

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 covers return values, and plural results are hinted at, so the definition is adequate for a simple lookup. However, with no annotations and no schema parameter description, the accepted hex format and the read-only nature are left undocumented.

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 there is one parameter, so the description must compensate. It adds that the value is a hex color and that matching is exact, but does not specify the accepted format (leading '#', case sensitivity, 3- vs 6-digit shorthand), leaving a real gap for the only input.

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 (find) and resource (token), plus 'reverse lookup' clarifies the direction of the query relative to a normal color lookup. It does not distinguish itself from the sibling list_tokens, but the purpose is unambiguous.

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

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

'Reverse lookup' hints at when the tool applies, but there is no explicit when-to-use guidance, no exclusion of alternatives such as list_tokens, and no stated prerequisites. The agent must infer the routing condition.

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

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

No annotations are provided, so the description carries the full burden. It discloses read-only safety and that no files are modified, plus the return shape (group names, member counts, parent objects). It stops short of some details like ordering or whether results are exhaustive across workspace boundaries, but the safety profile is well covered.

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

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

Well structured and front-loaded with the key 'Read-only. Returns ALL...' statement. Minor redundancy: 'Read-only' is stated at the top and repeated under 'Side effects', and the return format is listed despite an output schema existing.

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-param read-only listing tool, the description covers purpose, usage, safety, and return shape. An output schema exists, so the explicit 'Returns' block is somewhat redundant but harmless, and no critical invocation info 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 and the description explicitly states 'Parameters: None.' Baseline is 4 for a 0-param tool, and nothing here contradicts or adds 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 (returns/lists) and resource (semantic token groups) with concrete examples ('Actions', 'Dashboard', 'Settings'). It explicitly distinguishes itself from list_tokens, so an agent can tell them apart 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 explicit 'When to use' and 'When NOT to use' sections, and names the alternative (list_tokens) for individual tokens with the reason (groups are based on object declarations). Routing is fully specified.

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

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

No annotations exist, so the description carries the burden, and it does well: it declares read-only behavior, names the .bridge.bak backup source, and confirms no files are modified. It stops short of disclosing edge behavior — e.g. what happens when no backup exists or how large files are handled — which keeps it below 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. Slight redundancy — read-only is stated three times, and the parameter example duplicates the usage note about matching list_modified_files entries.

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 summarizes the return shape (original, modified, unified diff) for quick scanning. Combined with the safety profile and the list_modified_files prerequisite, an agent has everything needed to invoke this 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 compensate, and it does: file_path is explained as relative to project root with two concrete examples. It doesn't cover failure semantics for an invalid or non-modified path, leaving a 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 ('Returns before/after content and unified diff for a specific modified file') and goes further by explaining the computation (backup vs on-disk). The agent can distinguish this from list_modified_files or approve_file_changes without opening the schema.

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

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

Explicitly names when to use (inspecting changes before approve_file_changes / reject_file_changes) and when not to (needs list_modified_files first). Sibling tools are named as alternatives 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?

With no annotations, the description carries the full burden and does disclose the safety profile: 'Read-only. No files modified.' It also describes the return shape (detected style, confidence, examples, recommendations). It stops short of auth/rate-limit context, but for a pure analysis tool this is solid disclosure.

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 skimmable and front-loaded. There is mild redundancy between the opening 'Read-only analysis. Detects...' line and the 'What it does' line that restates the same detection 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 single-parameter read-only tool it covers everything an agent needs: purpose, routing to/away from siblings, side effects, parameter values, and returns. An output schema exists, so the added return summary is a bonus rather than a requirement.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it documents token_type as 'dimension' (default) or 'color', supplying the enum-like values the schema omits. It adds real meaning beyond the raw schema, though there is only one parameter to explain.

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

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

States a specific verb+resource: detects the token naming convention (camelCase/snake_case/PascalCase) used by the project. It is clearly distinguishable from siblings like list_tokens or add_token, and the scope is unambiguous.

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

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

Explicitly says when to use (BEFORE creating tokens with add_token or replace_pattern) and when not to use (do not use to inspect token values; use list_tokens instead). Both the alternative and the condition that selects it are named.

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

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

No annotations are provided, so the description carries the behavioral burden alone. It conveys that this is a status query returning named fields, which implies a non-mutating read, but it never states that explicitly and says nothing about auth requirements, freshness/caching of the status, or whether the call has any side effects.

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, front-loaded with the verb and resource, followed immediately by the three fields it returns. Every clause earns its place with no filler or repetition.

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

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

An output schema exists, so the description need not explain return values, and its field list is a helpful preview. For a zero-parameter read tool this is nearly complete; the only gap is the absence of any confirmation of read-only behavior or guidance versus the sync-triggering sibling.

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 document and the baseline is 4. The description correctly does not invent or discuss parameters, keeping the focus on the returned state.

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

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

The description names a specific verb ('Get') and resource ('sync status') and enumerates the returned fields (agent_busy, queue_count, snapshot_version), so the agent knows exactly what the call produces. It does not differentiate itself from the sibling 'trigger_user_sync', which is the main nearby alternative an agent might 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?

There is no explicit when-to-use statement, no prerequisites, and no mention of alternatives such as trigger_user_sync for kicking off a sync versus this tool for observing one. The name implies a read-oriented diagnostic, but the description itself supplies no 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?

With no annotations, the description carries the full burden. It discloses useful output content (file:line sites, enclosing composable, count of affected elements) which implies a safe read-only operation, but it never states that it is non-mutating, whether it requires the project to be indexed/synced, or any latency/scope limits.

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 purpose, then grouped into short labeled blocks (Shows / Use this / Args / Returns) with no filler. Every line contributes something an agent needs.

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

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

An output schema exists, so return values need not be re-explained, yet the description still summarizes them helpfully. The main remaining gap is the absence of behavioral/permission context, but for a low-risk read-only analysis tool it is largely 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 compensate. It gives concrete value examples for token_name ('welcomeCardHeight' or 'Primary') and clarifies that project_path is an optional explicit path to the project root, which meaningfully clarifies both 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?

States a specific verb and resource ('Get impact analysis for a specific token') and enumerates the three things it reports (usage sites, enclosing @Composable, total affected UI elements). This is clearly distinguishable from sibling token tools such as find_token_by_color or list_tokens.

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

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

'Use this BEFORE changing a token to understand the impact' gives an explicit temporal/decision context for calling it, which is strong for a read analysis tool. However, it names no alternative (e.g., when to use get_token_siblings or list_tokens instead), so it stops short of full when/when-not routing.

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

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

With no annotations provided, the description carries the full behavioral burden and discloses that the tool is read-only, modifies no files, excludes the original token, and returns an empty list when there are no siblings. It also describes the return payload at a high level, though it omits error behavior such as what happens when token_name is invalid.

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 clearly structured and front-loaded with the core behavior, then usage guidance, exclusions, side effects, parameters, and returns. It is appropriately sized, though 'Read-only' is repeated in both the opening 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?

This is a simple one-parameter read-only tool with an output schema, and the description covers purpose, usage, exclusion behavior, side effects, parameter semantics, and return shape. Given the low complexity and existing output schema, an agent has enough information to select and invoke 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 compensate for the undocumented token_name parameter. It does so by explaining that token_name accepts an exact token name like 'Primary' or a fully-qualified name like 'AppColors.Primary', which is the key semantic detail needed to invoke the tool correctly.

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 returns semantically related token variants such as PrimaryDark and PrimaryLight, with concrete examples. The purpose is clear, though it does not explicitly name sibling tools such as list_tokens or find_token_by_color to sharpen differentiation.

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

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

It gives clear when-to-use guidance: exploring related tokens or checking existing color variants. It also states a boundary condition that the original token is excluded and an empty list is returned when no siblings exist, but it does not name alternative tools or compare against 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?

No annotations are supplied, so the description carries the full burden. 'List' reliably signals a read-only, non-destructive operation, and the output schema covers return values. Still, it says nothing about whether a gradle environment must exist, whether the result is static or project-dependent, or any auth/rate constraints.

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

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

A single well-formed sentence with no wasted words, and the resource and its relationship to run_gradle_build are front-loaded. Nothing to trim.

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

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

With no parameters, an output schema handling the return value, and a simple read-only nature, the description is nearly complete for the agent's needs. The only missing nuance is whether the allowed-task list is static/configured or dynamically derived, which the agent might want to know.

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 rubric the baseline is 4. There is nothing for the description to disambiguate, and its only job — explaining what is enumerated — is done.

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 ('List') and resource ('gradle tasks') with the added scoping qualifier 'that can be run via run_gradle_build', which ties it directly to the sibling it complements. It is clear and unambiguous, though it does not explicitly contrast itself against the broader 27-tool sibling set.

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

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

The phrase 'that can be run via run_gradle_build' strongly implies the tool should be consulted before invoking run_gradle_build, giving usable implied guidance. However, there is no explicit statement of when to use this versus alternatives, nor any prerequisite or exclusion conditions.

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

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

No annotations are provided, so the description carries the full burden. It discloses the filtering behavior (only rollbackable patterns are returned), which is genuine context, but says nothing about read-only safety, permissions, or result size; an output schema exists so return values need not be 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?

A single short sentence with the resource and the scoping filter front-loaded. Every word earns its place and there is no filler.

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

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

For a zero-parameter read-only listing tool with an output schema, the description covers what is returned and the key filter. Only minor behavioral context (read-only nature, result size/pagination) is absent.

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 convey. Baseline 4 applies; the description neither adds nor detracts anything 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 ('List all applied patterns') plus a scoping qualifier ('that can be rolled back'), which separates it from the mutation siblings rollback_pattern and rollback_last. It stops short of explicitly naming those siblings, so it is clear but not maximally differentiated.

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 'that can be rolled back' implies this is the discovery step preceding rollback_pattern, but no when-to-use, when-not-to-use, or named alternative is given. Usage must be inferred from the sibling list rather than the text.

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

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

With no annotations, the description carries the full burden and does substantially: it declares read-only, no side effects, session-bound persistence, and that the source is the session journal rather than git status. It stops short of documenting authorization requirements or failure modes, so it is strong but not exhaustive.

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

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

The sectioned layout (What it does / When to use / When NOT to use / Side effects / Returns) is well front-loaded and scannable. There is mild redundancy—'Read-only' appears both in the opening line and again under Side effects—but the text is otherwise tight and 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?

An output schema exists, so return values need not be spelled out, yet the description still notes a JSON list of relative file paths. Combined with the session-boundary and source-of-truth caveats, nothing an agent needs to call 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?

The tool takes zero parameters, which per the rubric sets a baseline of 4. The description confirms 'Parameters: None,' accurately matching the empty schema, so there is no gap to compensate for.

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 scope: 'Lists files modified by recent replace_pattern operations in the current session.' It also distinguishes itself from the related get_file_diff sibling by clarifying it returns journal state, not git status, so an agent can pick between them without opening either schema.

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

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

Explicitly provides 'When to use' (view unapproved changes before approving/rejecting) and 'When NOT to use' (does not persist across sessions; use get_file_diff for git-based modifications). This is the full when/when-not/alternative pattern, 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?

With no annotations provided, the description carries the full behavioral burden. It explains what an orphan is (registered but never used) and that results echo token locations, which is useful semantic context, but it never states that this is a side-effect-free read operation, nor does it mention permission, project-load, or cost/rate considerations.

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 definition, then rationale, use case, args, and returns. Every section is short and earns its place; the 'design system clutter' line is slightly editorial but still supports the usage guidance.

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 with an output schema already covering return structure, the description adds the needed conceptual and parameter context. Nothing critical is missing, though a note that it is a safe read operation would close the remaining gap left by absent annotations.

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, and it does by documenting the single parameter ('project_path: optional — explicit path to project root'), clarifying its role and optionality beyond the bare schema title.

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

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

States a specific verb+resource (list orphan tokens) and defines the key term inline ('registered but never used'), which immediately distinguishes it from the generic list_tokens sibling without the agent 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?

Gives a clear motivating context ('identify tokens that can be safely removed or that need to be used in the codebase'), telling the agent when this tool is useful. It does not, however, name alternatives such as list_tokens or state any exclusion conditions, so it stops short of the explicit when/when-not routing a 5 requires.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the shape of the returned report (four token categories), which is useful, but says nothing about read-only safety, side effects, permissions, or performance on large projects.

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 action and a scannable bullet list of return categories, then the usage hint. The trailing 'Args:' block largely restates the schema, a minor redundancy, but the prose is otherwise tight.

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-param read tool, the description covers purpose, usage timing, and report contents. An output schema exists, so explaining return values is not strictly required, and the remaining gaps (default path behavior, read-only guarantees) are modest.

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, and it does document the single parameter as 'optional — explicit path to project root.' However, it never states what happens when the path is omitted (e.g., auto-detection of project root), leaving the default behavior 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+resource ('List all design tokens in the project') and enumerates what the report contains (registered, hardcoded, duplicate, orphan tokens). It does not differentiate itself from overlapping siblings such as list_orphans or get_all_token_groups, which the report categories partially duplicate.

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

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

'Use this to understand the project's design system before making edits' gives a clear situational context for calling the tool. There are no exclusions or named alternatives, so it stops short of the 5-level 'when-not/alternatives' guidance.

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

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

With no annotations, the description carries the full burden and does so: it leads with 'Destructive:', explains the byte-for-byte rollback via .bridge.bak backups, states that all modified files are overwritten, that the journal is cleared, and that a status list is returned. This is exactly the behavioral context an agent needs for an irreversible write.

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 with the destructive warning and every line is scannable. The 'Returns' block is mild duplication given an output schema exists, but it costs little.

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 with an output schema and no annotations, the description covers trigger, exclusion, side effects, and return shape. Nothing an agent needs to invoke it safely 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; the description's 'Parameters: None.' confirms the no-argument contract rather than adding meaning. Nothing more is needed.

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

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

States a specific verb+resource (rolls back all files modified in the current journal session) and explicitly differentiates itself from the two closest siblings, reject_file_changes and reject_all_files_force. An agent can select it 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' and 'When NOT to use' sections name the alternatives and the exact condition that routes to each ('reject_file_changes for a single file', 'reject_all_files_force if some rollbacks may fail'). 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?

No annotations are provided, so the description carries the full burden. It discloses that journal tracking is cleared regardless of clean reversion and that files may be left in an inconsistent state — strong destructive-behavior disclosure. It stops short of stating permission/auth requirements or reversibility options, leaving a minor gap.

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

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

Labeled sections (What it does, When to use, When NOT to use, Side effects, Parameters, Returns) are well organized and front-loaded with the 'Destructive + Forceful' warning. The journal-clearing behavior is stated twice (opening line and side effects), a small redundancy, but nothing is wasted overall.

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 zero parameters, a present output schema, and no annotations, the description covers purpose, usage conditions, exclusions, side effects, and parameter count — everything an agent needs to invoke it correctly. Return values needn't be explained since an output schema exists.

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 the baseline is 4. 'Parameters: None' correctly and explicitly confirms this, adding the only clarification needed.

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 ('forcefully attempts rollback and clears the journal unconditionally') and distinguishes itself from the sibling reject_all_files by scope and failure tolerance. An agent can tell it apart 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' (only when reject_all_files fails due to missing backups or corruption) and 'When NOT to use' (may leave files inconsistent; use reject_all_files for safe rollback). Names the alternative and the selecting condition directly.

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

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

With no annotations, the description carries the full burden and does so well: it flags 'Destructive', states the file is overwritten from the original backup and that the journal entry is removed, which tells the agent the change is discarded rather than merely marked. It omits auth/permission needs and the failure mode when no pending change or backup exists, keeping it short of a 5.

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

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

Front-loads the destructive warning and then uses labeled sections, so an agent can scan for the relevant part quickly. Slightly padded by the trailing 'Returns: JSON string confirming rollback' line, which duplicates what the existing output schema already conveys.

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, when/when-not, side effects, the sole parameter, and the alternative sibling; the return value is already defined by an output schema, so the brief mention is a bonus rather than a gap. An agent has everything needed to call this destructive tool safely.

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, and it does: file_path is documented as relative to project root with two concrete examples. For a single simple string parameter this is sufficient, though no guidance is given on path format edge cases (absolute paths, separators).

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 scope: reverts pending changes for a SINGLE file, explicitly contrasting with reject_all_files for the multi-file case. The mechanism (.bridge.bak backup, byte-for-byte rollback) further disambiguates it from approve/reject 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?

Gives an explicit 'When to use' condition (modifications to a specific file are incorrect) and an explicit 'When NOT to use' precondition (file must be currently modified), then names the alternative tool reject_all_files for the all-files case. 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?

With no annotations, the description carries the full burden and does so: it labels the operation DESTRUCTIVE, notes it modifies multiple .kt files simultaneously, records changes in a journal, and specifies rollback via rollback_pattern(pattern_id). Safety, reversibility, and write scope are all disclosed.

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 clear headers, which aids scanning. It is slightly verbose, restating destructiveness in the header and again under side effects, but every section remains relevant.

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 documented, yet the description still summarizes the JSON result. Combined with the usage, safety, rollback, and parameter detail, nothing an agent needs to call this destructive tool 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% (titles only), so the description must compensate and does: pattern_id is defined as a unique identifier sourced from detect_conditional_variants, and dry_run is explained as previewing changes without writing to disk. Both parameters gain meaning beyond 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 (replaces) with resource (pattern occurrences across the project) and scope (ALL, batch). It explicitly routes the agent by naming detect_conditional_variants as the origin of pattern_id and rollback_pattern as the inverse, so it's distinguishable from all 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?

Provides explicit 'When to use' and 'When NOT to use' sections, requiring a dry_run preview first and mandating the pattern_id come from detect_conditional_variants. This is exactly the when/when-not/alternative guidance the rubric reserves top marks for.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It does usefully bound the behavior (only the most recent edit, only the current session, only surgical edits), but says nothing about whether the rollback is itself reversible, what happens when there is no prior edit, or any permission requirements.

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

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

A single front-loaded sentence with no filler. The most decisive constraint ('LAST') is placed early, and every word 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?

An output schema exists, so return values need no explanation. However, with no annotations on a state-mutating revert operation, the missing safety and failure-mode context leaves the definition only marginally complete for an agent deciding whether to call it.

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

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

The tool takes zero parameters, so there is nothing for the description to annotate and the baseline of 4 applies. No parameter-level clarification is needed or missing.

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?

Clear verb (reverts) plus a precisely scoped resource (the LAST surgical edit in the current session). An agent can distinguish it from the sibling rollback_pattern, though 'surgical edit' is left undefined, so the boundary of what qualifies is not fully nailed down.

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 scope qualifiers ('LAST', 'current session') imply context, but the description never states when to reach for this tool versus the sibling rollback_pattern, nor any preconditions or exclusions. An agent must infer the choice.

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

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

No annotations are provided, so the description carries the full burden, and it does well: it flags destructive rollback, byte-for-byte reversion, and the limitation that externally modified files cannot be undone. It omits details like permissions or whether the rollback itself is reversible, keeping it just 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 the action, then cleanly sectioned into use/not-use/side-effects. The 'Returns' line is somewhat redundant since an output schema exists, but the overall structure is tight and scannable.

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 with no annotations, it covers purpose, routing, side effects, prerequisite parameter source, and error limits. With an output schema present, its return summary is a bonus rather than a 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 must compensate. It explains pattern_id as the exact pattern_id from the original replace_pattern response, which is more than the bare 'Pattern Id' title conveys, though no format example is given.

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 scope (ALL changes made by a specific replace_pattern call). Clearly differentiates itself from the sibling rollback_last, which it names 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?

Explicit 'When to use' (replace_pattern caused regressions needing complete reversal) and 'When NOT to use' (files modified externally), plus a direct alternative (rollback_last for single-edit undo). All 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the whitelist enforcement and the 5-minute default timeout, but says nothing about side effects (build artifacts written to disk), environment prerequisites, or whether it is a long-running/blocking operation. The safety and side-effect profile of an execution tool is left unstated.

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

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

Front-loaded with the core action, then cleanly sectioned into Args and Returns. Every line is short and purposeful. The Args/Returns headers are slightly redundant given the schema, but the whitelist values inside them 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 two-parameter tool with an output schema present, the description covers purpose, usage, allowed task values, timeout, and result shape adequately. What is missing is behavioral context that annotations would normally supply, such as side effects and execution environment, keeping it from 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 compensate, and it does: it enumerates the accepted task values (assembleDebug, assembleRelease, test, lint, clean) that the schema does not expose as an enum, and states the timeout default in human terms. The one gap is that the timeout is not described as seconds-vs-milliseconds beyond the field name.

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

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

The description opens with a specific verb and resource: 'Run a Gradle task and return structured result.' That is unambiguous and distinct from sibling tools like list_allowed_gradle_tasks. It stops short of naming an adjacent sibling to differentiate itself explicitly, so it lands at a strong 4 rather than a 5.

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

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

It gives a clear use case: 'verify that code changes compile successfully before continuing with more changes,' which tells the agent when this tool belongs in a workflow. It does not state when NOT to use it or name an alternative (e.g. the sibling that lists allowed tasks), so it is clear context without explicit exclusions.

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

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

With no annotations, the description carries the full burden and delivers: it flags DESTRUCTIVE on-disk source modification, discloses auto-migration to BridgeTextRegistry, states the approve_file_changes gating requirement, and documents reversibility via reject_file_changes. This is exactly the behavioral context an agent needs before a mutating call.

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?

Strongly front-loaded with labeled sections (destructive warning, what/when/when-not, side effects, params, returns). Minor cost: 'Modifies .kt files' is restated three times, creating slight redundancy that could be trimmed.

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, safety, approval workflow, per-parameter meaning, and even return contents (success status, old_text, new_text, file location) despite an output schema existing. 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?

Schema coverage is 0%, so the description must compensate and does: token_name is explained as EITHER a reference key (with an example format) OR exact old text content, new_value and file_path get examples, and line is explained as optional disambiguation for repeated text. This adds meaning well beyond 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 ('Surgically edit text content', 'Modifies .kt files') and scopes it to UI text strings including hardcoded Text("...") elements. It clearly differentiates itself from siblings set_token and add_token, so an agent can select it 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 and complete: 'When to use' names editing UI text strings, and 'When NOT to use' routes colors/dimensions to set_token or add_token. Both the triggering condition and the excluded alternatives are spelled out.

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

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

With no annotations present, the description fully carries the behavioral burden: it flags DESTRUCTIVE, discloses on-disk source mutation and the WebSocket phone notification, and specifies the approve_file_changes/reject_file_changes commit-revert workflow. This is exactly the safety context an agent needs before a mutating call.

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?

Sections are labeled and the destructive warning is front-loaded, so it is easy to scan. The 'Returns' block largely restates the output schema, which is mild redundancy that slightly dilutes conciseness.

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 with no annotations, the description covers purpose, routing, side effects, workflow prerequisites, parameter formats, and even a return summary. An agent has everything required to invoke 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 coverage is 0%, so the description must compensate and does: it explains token_name accepts either a bare name or a 'AppColors.TokenName' form, and that value is '#RRGGBB' for colors or numeric/'24.dp' for dimensions, with concrete examples for both.

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 constrains the target to .kt files containing the token definition. It also distinguishes itself from closely-named siblings (set_text, add_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?

Explicit 'When to use' (adjusting a color/dimension token with live feedback) and 'When NOT to use' sections that name the alternative tools for the excluded cases (set_text for strings, add_token for hardcoded-to-token conversion). Routing is unambiguous.

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

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

With no annotations provided, the description carries the burden and does disclose the crucial behavioral trait: 'Read-only analysis' and 'Side effects: Read-only. No files modified.' This tells the agent it is a safe, non-mutating operation. It does not address permissions, error behavior, or performance, so it falls 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 the read-only qualifier, then organized under labeled sections (What it does / When to use / When NOT to use / Side effects / Parameters / Returns). Every line earns its place and nothing is redundant, making it easy to scan.

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

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

Even though an output schema exists, the description briefly signals the return shape ('split suggestions, proposed token names, and affected call sites'). Combined with the routing guidance and side-effect disclosure, an agent has everything required to select and invoke this 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 compensate, and it does: token_name is described as an 'optional filter to analyze a specific token only' and project_path as an 'optional override for project root path'. Both parameters get meaning and their optional nature is clear, though no format or default guidance beyond that.

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

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

States a specific verb+resource ('suggests splitting tokens used in multiple contexts') and adds a concrete definition of the detection logic with an example ('cards and buttons'). It explicitly names sibling tools (get_token_impact, get_token_siblings) so an agent can separate this from adjacent analysis tools.

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

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

Provides explicit sequencing ('Use BEFORE replace_pattern'), plus named alternatives for other intents ('For token impact analysis use get_token_impact. For sibling tokens use get_token_siblings.'). Both when-to-use and when-not-to-use are covered with concrete routing.

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

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

With no annotations, the description carries the full burden and does disclose the core effect (all queued edits applied to files) plus a gating condition (agent must not be busy). It omits failure behavior, whether the operation is blocking, and reversibility, even though a rollback_last sibling exists that implies undo semantics.

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 action, then the effect, then the precondition. The trailing 'Returns:' block is somewhat redundant because an output schema exists, but it is short and does not bloat the 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?

With an output schema present, the return explanation is unnecessary but harmless; the description covers effect and precondition, and there are no parameters to document. It stops short of explaining what 'skipped' or 'errors' mean operationally or how to recover, which is the only real 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?

The tool takes zero parameters, so there is nothing for the description to compensate for; baseline is 4. The empty schema is fully consistent with the described no-argument trigger.

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 ('Trigger user_sync on the Bridge Server') and adds what the action actually does: applying queued dimension/color edits to files. It does not, however, distinguish itself from nearby siblings like get_sync_status or approve_all_files, which also deal with pending sync state.

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 line 'Only works when the AI agent is not busy' gives a real precondition for invocation, which is more than most. But there is no guidance on when to prefer this over get_sync_status (checking state) or approve/reject tools (managing the queue), leaving the routing to inference.

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