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

Path validation before applying is a concrete behavioral guarantee beyond the annotations. The destructiveHint annotation already signals that the operation can alter files, and the description adds a safety-relevant precondition. It does not elaborate on rollback or partial-failure behavior, but the annotation coverage lowers the burden.

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

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

Three short sentences convey purpose, safety behavior, and routing guidance with no filler. The most important directive is front-loaded, and every sentence earns its place.

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

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

For a mutation tool with destructiveHint provided, the description covers purpose, safety validation, and sibling selection. The absence of an output schema is not a major gap because the main usage decision is clearly scoped. A minor omission is explicit failure semantics, but the description remains complete enough for correct invocation.

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

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

Schema description coverage is 100%, with clear parameter descriptions for patch and workspace_id. The tool description adds little parameter-level detail beyond the schema, which matches the baseline of 3. No undocumented parameters need compensation.

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: 'Apply one unified diff patch inside the workspace.' It also distinguishes the tool from the sibling edit tool by framing apply_patch as the multi-file diff option. This gives an agent a clear identity for selection.

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 when to use which tool: 'Prefer edit for tiny replacements and apply_patch for multi-file diffs.' This direct alternative-selection guidance eliminates ambiguity between the two most similar 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 carry the non-read-only, open-world, non-idempotent, and destructive hints. The description adds valuable behavioral constraints beyond annotations: only one allowlisted command may be run, and shell composition via &&, pipes, redirects, or file readers is prohibited. This meaningfully clarifies the tool's execution model without contradicting 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?

Three sentences, front-loaded with the primary purpose, followed by exclusions and alternatives. Every sentence earns its place, and there is no repetition of schema field descriptions or annotation content.

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

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

The description is complete for a command-execution tool: it defines the allowed scope, lists examples, names sibling tools for excluded use cases, and specifies important command-construction limits. Annotations cover safety and open-world traits, and the schema covers parameter details, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema's simple 'Command to run' by defining acceptable commands as allowlisted verification commands and forbidding chaining and shell constructs. Other parameters like cwd, timeout_ms, and workspace_id are already adequately described 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?

The description states precisely that the tool runs one allowlisted verification command in the workspace, listing examples such as tests, build, lint, typecheck, and project scripts. It also distinguishes itself from siblings by explicitly excluding git status/diff and file inspection, which are routed to show_changes, tree, search, and read.

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

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

The description gives explicit when-to-use guidance: verification commands like tests, build, lint, typecheck, or project scripts. It also gives explicit when-not-to-use guidance for git status/diff and file inspection, naming the alternative tools, and warns against chaining commands with &&, pipes, redirects, or shell file readers.

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 description discloses important stateful behavior beyond the annotations: pools survive MCP requests, route back to their bound workspace by id, and reconnects can reset implicit workspace selection. This is exactly the kind of contextual, non-obvious behavior an agent needs to know, and it does not contradict the provided 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?

Four dense sentences with the most critical warning front-loaded before the lifecycle advice. There is no filler, though 'stable h5i boxes' is jargon that could be clearer for an unfamiliar agent.

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

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

For a multi-action tool with no output schema, the description explains the persistence and reconnect model well but leaves the semantics of actions like wait, status, messages, checkpoint, and stop to be inferred from the enum and parameter names. It is adequate for tool selection but not fully complete for invoking every action 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 67%, and the description mostly re-emphasizes the documented root requirement for action=start rather than explaining undocumented parameters like force, agents, or advance_baseline. It adds lifecycle context but does not materially clarify individual parameter behavior beyond what the schema already provides.

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

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

The description identifies the tool as a 'unified persistent codex agent interface' and clearly describes the start/send lifecycle with 'Start once, then send many tasks', so an agent can tell it governs persistent Codex agents. It does not explicitly contrast it with sibling tools like bash or workspace, so it falls short of a 5.

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

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

It gives a concrete, high-value usage rule: for action=start ALWAYS pass the explicit Git repository root because MCP reconnects can reset implicit workspace selection. It also recommends a lifecycle pattern ('Start once, then send many tasks'), but it does not explicitly state when not to use the tool or route to an alternative.

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 carry the destructiveHint, and the description discloses three additional behaviors: in-place modification (inode/metadata preserved), the unified-diff return value, and SHA-based stale-eidt rejection. These give the agent concrete side-effect expectations that the annotation flags alone do not provide.

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

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

Two sentences, front-loaded: the first states the action and the key in-place invariant, the second covers the return value and concurrency safety. There is no filler and no repetition of schema content.

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

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

For a destructive 7-parameter mutation tool with no output schema, this is close to complete: it states the action, the return format (diff), and the stale-eidt safety mechanism (SHA). It stops short of 5 by not addressing the no-unique-match failure mode or explicit use-vs-sibling boundaries, though the schema's old_text description partially covers match uniqueness.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, and the description's SHA mention merely echoes the schema's expected_sha256 text ('Optional SHA-256 from read'). Baseline 3 applies; the description does not materially deepen parameter meaning.

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 action ('Apply a targeted exact text replacement') and a distinguishing invariant ('retaining the existing file inode and metadata'), which separates it from write (full overwrite) and apply_patch (patch-based). It goes well beyond the tautological title 'Edit File'.

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 phrasing 'targeted exact text replacement' and the SHA-from-read workflow imply surgical edits performed after reading the file, but the description never explicitly states when to prefer edit over write, apply_patch, or bash. The when-to-use guidance is inferable rather than 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?

Annotations already establish readOnlyHint=false and destructiveHint=true, and the description adds valuable nuance: 'Overwrite is off by default,' clarifying that the destructive behavior is opt-in via the overwrite parameter rather than unconditional. The narrow input contract is also disclosed. There is no contradiction — 'Import' aligns with a write operation and the destructive hint.

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

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

Four short sentences, each with a distinct job: main action, input contract, exclusion, and default behavior. The most decision-relevant constraint (only platform file objects) is front-loaded, and there is zero filler or repetition of schema content.

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

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

With a 100%-covered schema and annotations present, the description covers scope, defaults, and exclusions well enough that an agent can invoke the tool correctly. The one gap is that there is no output schema and the description does not say what the tool returns on success (e.g., imported path, status, or file metadata) — minor for invocation but relevant for downstream steps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the file contract (download_url, file_id) and the overwrite default, but those facts already appear in the schema with equivalent phrasing — 'Default: false' and required fields on the nested file object. It adds no net-new parameter meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Import a ChatGPT Apps SDK attachment into the workspace,' immediately telling the agent what is operated on and where. It tightens scope with 'Accepts only a platform file object with download_url and file_id' and further differentiates itself with 'Not a general URL downloader,' which prevents confusion with any broad fetch-like tool among the 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?

The description gives clear context on when to use the tool (importing ChatGPT SDK attachment objects) and an explicit when-not ('Not a general URL downloader'). It stops short of a 5 because it never names a sibling alternative for the excluded case — e.g., it doesn't say 'use bash or write for general URLs' — leaving the routing to an alternative partially implicit.

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 description discloses persistence across MCP requests, pool-to-workspace binding by id, and the reconnect reset risk, all of which go beyond the annotations. DestructiveHint=true is already declared, so the description does not need to fully enumerate destructive side effects, but it could still add more detail about stop/checkpoint behavior.

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

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

The description is four dense sentences with no filler. The most safety-critical instruction about explicit root and reconnect behavior is front-loaded, and the pool persistence model is conveyed efficiently.

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 seven actions, 12 parameters, and no output schema, the description only meaningfully contextualizes start and the persistence model. Actions like checkpoint, status, messages, stop, and advance_baseline are left mostly to inference, making the definition incomplete for such a complex tool.

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

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

The schema already documents several parameters such as root, pool, task, agent, message, wait_seconds, and workspace_id. The description adds critical meaning around root and workspace binding, but for a 12-parameter multi-action tool it does not compensate for the many action-specific parameters that remain unexplained.

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 clearly identifies a persistent agent interface and explains the core workflow: start once, then send many tasks. It is not a tautology and provides meaningful detail beyond the title, though it does not enumerate the seven action modes 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 explicit operational guidance: ALWAYS pass the Git repository root for action=start, and explains why MCP reconnects can reset implicit workspace selection. It does not mention alternatives, but no sibling tool directly overlaps, so the usage context is clear.

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 and destructiveHint=false, covering the safety profile. The description adds the line-number output behavior and the text-file-only scope, which is useful context. It does not explain behavior for missing/binary files, but that is a minor gap given annotation coverage.

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

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

Two sentences with no fluff: the core action and output format are front-loaded, followed by a single high-value usage warning. Every sentence earns its place.

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

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

For a read-only file tool, the description is nearly complete: schema covers all parameters, annotations cover safety, and the line-number aspect covers the return format. It doesn't mention edge cases like binary files or missing files, but those are not critical given the tool's simplicity and the existing documentation.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description adds no parameter-specific meaning, which is acceptable because the schema carries the burden. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Read'), resource ('a specific text file'), and a distinctive output trait ('with line numbers'). The 'text file' qualifier helps differentiate it from sibling view_image, and the action is clear.

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-not guidance: 'Avoid rereading files after write/edit/apply_patch unless exact final content is needed.' This is practical and actionable, though it does not name an alternative tool to use instead, so it falls just short of a full when/when-not/alternatives statement.

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 and destructiveHint=false, so safety is covered. Description adds only usage guidance, not structural/behavioral details like result limits, regex dependency, or intent semantics; nothing contradicts 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?

Two terse sentences with no filler; the primary use case is front-loaded and the anti-pattern ('repeated broad verification searches') is stated in one phrase.

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

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

For a 10-parameter tool with an intent enum and symbol override, the description gives little orientation beyond 'code lookup' and the one-search preference. The schema descriptions carry the burden; an agent can still call it correctly, but a note on when to use symbol/intent modes or when read/tree would be better would make it complete.

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

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

Schema description coverage is 100%, so parameter meanings are already documented (query, glob, regex, intent, symbol, etc.). The description adds no parameter-specific guidance, so it stays at the baseline 3 rather than compensating further.

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?

Title and description identify a file-content lookup operation ('targeted verification or code lookup') with a clear resource. It distinguishes the tool from sibling read/tree by emphasizing targeted final search rather than broad repeated scans, though it doesn't name alternatives 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?

Description explicitly states when to use ('targeted verification / code lookup') and imposes a usage rule ('Prefer one specific final search instead of repeated broad verification searches'). It doesn't enumerate alternative tools, but gives enough context to choose search over broad repeated verification.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description omits a significant behavioral trait: the tool tracks a 'last_shown' review checkpoint and can suppress unchanged repeated reviews, with mark_reviewed updating that state. This stateful behavior is not disclosed in the description and is not covered by the read-only annotation, so the agent may be surprised when subsequent calls differ.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the usage guidance is embedded efficiently. Every sentence earns its place.

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

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

The description is adequate for a read-only summarization tool with schema-documented parameters, and it names the output components. However, the stateful checkpoint behavior is a notable gap: without knowing that repeated calls can be suppressed via 'last_shown' and that mark_reviewed mutates internal state, an agent could misuse the tool or misread its output. With no output schema and 6 parameters, this missing context lowers completeness.

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

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

Schema description coverage is 100%, and every parameter has a description. The tool description itself adds no extra parameter semantics beyond the schema, so the baseline of 3 applies. The description does not clarify parameter interactions (e.g., how since and mark_reviewed relate), but the schema already covers basic meanings.

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 ('Summarize'), a clear resource ('current workspace changes'), and names the exact output composition ('git status, diff stats, and optional diff'). It also distinguishes itself from sibling/alternative tools like git_status and git_diff, so an agent can immediately tell what this tool does and what it is not.

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

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

The description explicitly says 'Use this instead of bash git status, bash git diff, git_status, or git_diff when reviewing work.' This gives both the context ('when reviewing work') and the alternatives to avoid. Clear routing guidance is present, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the agent knows this is a non-mutating read. The description adds the behavioral detail that blocked paths are excluded from results, which does not contradict the annotations. It does not mention truncation at max_depth/max_entries or error behavior, but the annotation safety profile keeps the burden low.

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 12-word sentence that is front-loaded with the verb and object and contains no filler. 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?

For a simple read-only tool with zero required parameters and default values documented in the schema, the description plus schema plus annotations covers what it lists, what it excludes, and its safety profile. The only gap is that no output schema exists, so return-format expectations rest on 'List files and directories,' which is adequate for this tool's simplicity.

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

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

Schema description coverage is 100% with defaults documented for all five optional parameters (path, max_depth, max_entries, workspace_id, include_hidden). The description repeats nothing from the schema and adds no parameter-level semantics of its own, which is acceptable at baseline because the schema carries the load.

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 the specific verb 'List' with the resource 'files and directories inside the workspace,' and adds a scoping constraint ('excluding blocked paths'). It is clearly distinguishable from siblings like search or read by its action and resource, but it never names a sibling 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?

No sentence advises when to use tree instead of search, read, or workspace. For an agent deciding how to explore a workspace, the description provides no routing signal; the difference between listing the tree and searching file contents must be inferred from tool names alone.

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 mark the tool as read-only, non-destructive, and not open-world, so the description only needs to add context. It adds supported formats and the exact output metadata (dimensions and SHA-256), which gives the agent useful behavioral expectations beyond the safety 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?

A single sentence that front-loads the image formats and the returned data. Every clause earns its place, and there is no repeated schema information or 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 simple read-only image inspection tool, the description covers formats, source workspace, and return values; the schema covers all parameters and annotations cover safety. No output schema exists, but the description explicitly names what is returned, so an agent has what it needs 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 description coverage is 100%, so the schema fully documents path, max_bytes, and workspace_id. The tool description does not add further parameter-level meaning, and the baseline of 3 is appropriate when the schema carries the parameter burden.

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 ('Inspect'), a concrete resource (image files in PNG, JPEG, GIF, or WebP), and the expected return payload (native image content, dimensions, SHA-256). This clearly distinguishes view_image from generic siblings like read or tree without needing to open 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 clearly establishes the context: inspecting image files from the active workspace. It does not explicitly say when not to use it or name alternatives, but the image-specific scope and return type imply the correct selection against the generic sibling tools.

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 cover the read-only/non-destructive profile, so the description does not need to repeat that. It adds genuinely useful behavioral context: selection is scoped to this MCP session, other chats can select different projects through the same endpoint, and `discover`/`open` have a specific sequencing role relative to Git and Pi/Codex.

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

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

Three sentences with no filler: the core purpose is front-loaded, the conditional discover-then-open workflow follows immediately, and the session-scoping caveat closes with important concurrency context. Every sentence earns its place.

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

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

For a router with annotations covering safety and a schema covering most parameter semantics, the description gives enough to act correctly for the main Git/Pi/Codex workflow. The main gap is that `list`, `use`, and `current` are not described and no output shape is given, though their names and schema fields provide partial context.

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

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

Schema descriptions already cover most parameters, but the description adds meaning by tying `root` to a 'requested directory' and `discover` to the Git-repository condition. It also frames `max_depth` and `max_results` as repository-discovery settings, which helps select sensible values even though the schema already documents them.

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 ('Route this chat to an allowed project') and immediately distinguishes its workspace-routing role from the sibling file and execution tools. It also clarifies the core discover-vs-open distinction, making the tool's purpose unambiguous even before opening the schema.

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

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

The description gives explicit, actionable guidance: use `discover` when a requested directory is not a Git repository, then `open` the discovered repo before Git operations or starting Pi/Codex pools. It does not, however, explain when to use the other actions (`list`, `use`, `current`) or name exclusions for those cases.

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 indicate destructive and non-readonly behavior, and the description adds valuable behaviorl detail beyond that: atomic rename for new files, inode and metadata retention for existing files, unified diff return, and sha256 concurrency checking. These details help an agent predict side effects accurately, with no contradiction to 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?

Three sentences, each earning its place: purpose, filesystem behavior, and return/concurrency guidance. The purpose is front-loaded, and there is no redundent exposition or 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 write tool with full schema coverage and ruct annotations, the description captures purpose, filesystem behavior, return value, and concurrency handling. It does not mention failure modes (e.g., overwrite=false on an existing file) or encoding constraints, but those can be inferred from the schema and are not critical for correct invocation.

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

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

The schema already documents all 6 parameters at 100% coverage, so the baseline is 3. The description adds meaning by specifying how expected_sha256 should be used ('pass the SHA from read') and mentions the unified diff return. This is useful but does not deeply redefine the schema-provided semantics for each 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 opens with a clear verb and resource: 'Create or overwrite a meaningful text file inside the workspace.' This unambiguous scope distinguishes it from read (reading) and edit/apply_patch (modifying existing content). The term 'meaningful' is slightly subjective but does not obscure the core purpose.

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

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

The description states its primary use case (create or overwrite a text file) and offers concurrency guidance for shared files ('pass the SHA from read when overwriting shared files'). It does not explicitly contrast with alternatives such as edit or apply_patch, and does not say when not to use write, so it falls short of a full 5.

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