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

The description openly discloses the file-system mutation types, including delete and move, and suggests a dry-run safety check. This complements the destructiveHint annotation with concrete operations, though it does not detail failure or atomicity 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?

Two sentences, each earning its place: the first defines scope and operations, the second provides a practical safety instruction. No fluff or redundancy.

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, 100% schema coverage, and no output schema, the description plus structured fields provide everything needed to invoke properly: patch format, scope, supported operations, and a dry-run guardrail.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by naming the Codex patch format and giving a conditional usage rule for dry_run that is not in the schema. It does not add detail beyond schema for expected_sha256, but that is already well-documented.

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 specifies the exact action—applying a Codex patch—and the affected resources: files in the configured workspace, with explicit capabilities (add, update, move, delete). This clearly distinguishes it from sibling file tools like write_file/edit_file by patch format.

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 provides direct operational guidance to run with dry_run first when context lines are uncertain. It does not explicitly name alternatives or state when to prefer apply_patch over write_file/edit_file, but the patch-format reference supplies a reasonable context cue.

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 readOnly and non-destructive behavior, lowering the bar for description contribution. The description adds useful context by stating the records are 'redacted' and 'recent', which informs the agent about output content and time scope beyond the structured 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, well-formed sentence that immediately states the action and resource. There is no filler or redundant information, and the description is appropriately compact for a simple read tool.

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

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

The description is adequate for a straightforward read operation with readOnly annotations, but it lacks parameter semantics and usage guidance. For a one-parameter tool where the parameter is optional and schema-described, this is a minimum viable definition with clear gaps.

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

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

Schema description coverage is 0%, so the description should explain parameter meaning. It does not mention the 'limit' parameter at all, leaving the agent to infer its purpose from the schema's integer range alone.

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 ('read') and resource ('recent redacted machine-operation audit records'), which clearly identifies the tool's purpose. It does not explicitly distinguish this from the sibling audit_search, but the 'recent' and 'redacted' qualifiers provide meaningful 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?

The description gives no guidance about when to use this tool versus alternatives such as audit_search. There is no mention of what 'recent' means, how far back it reaches, or when a search-style tool would be more appropriate.

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

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

Annotations already communicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: records are 'recent' and 'redacted'. However, it does not specify what 'recent' means, how matching works, or what the result shape is.

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 a single seven-word sentence, front-loaded with the verb and resource. Every word contributes meaning and there is no repetition 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?

The core invocation is clear, and read-only annotations cover safety, but the definition leaves ambiguity around the time window for 'recent', the exact search semantics, and what redacted output contains. No output schema exists to fill these gaps.

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

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

Schema description coverage is 0%, so the description must compensate. 'By text' clarifies that query is the search text, but the limit parameter is not addressed at all. The schema's min/max constraints help, but the description adds only partial semantic value.

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 states the verb 'Search', the resource 'recent redacted audit records', and the method 'by text'. This distinguishes it from the sibling audit_recent, which likely lists recent records without text search.

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

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

The description implies text-based search over recent audit records, but it does not explicitly mention the sibling audit_recent or state when to prefer this tool over listing all recent records. No alternatives or exclusions are provided.

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, destructiveHint=false, and openWorldHint=false, and the description reinforces this with 'Read-only.' It adds useful behavioral context by stating what the comparison produces and what a mismatch means, though it does not go into deeper details like response format or potential failure modes. This is acceptable given the 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?

The description is three sentences with no filler. It front-loads the read-only nature, then states the action, outputs, and interpretation. Every sentence contributes meaningful information.

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

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

For a simple, zero-parameter read-only tool, the description is largely complete: it names the outputs and their diagnostic meaning. There is no output schema, but the description compensates well. A more advanced agent might want an example, but none is necessary 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 tool has zero parameters and the schema is empty with 100% coverage, so no parameter documentation is needed. Per the baseline for zero-parameter tools, a score of 4 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 operation ('Compare the live worker tool surface against a fresh probe of the current build'), identifies the resource being compared, and names the concrete outputs ('added/removed/changed tool names and fingerprintMatch'). This clearly distinguishes it from sibling tools like machine_status or runtime_info.

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 for when this tool is relevant: checking whether the worker serves a stale build by comparing live surfaces to a fresh probe. It does not explicitly name alternatives or exclusion conditions, but the intended diagnostic use is strongly implied.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful output-facing behavior, namely showing matching lines and the highest-priority matching context source, which goes beyond what the annotations provide. No contradiction exists.

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 a single sentence with the core purpose front-loaded and the optional behavior attached cleanly. There is no filler or redundant restatement of the tool name.

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

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

For a read-only introspection tool with two optional parameters and no required inputs, the description conveys the main purpose and the query variant effectively. It does not explain what determines 'highest-priority' or the exact output shape, but the annotations and simple schema make the tool usable without that extra detail.

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 input schema already documents both parameters fully with 100% coverage, including the path default and the optional literal query. The description restates the query behavior somewhat but does not add meaningful new parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb-resource pair: 'Explain where Pilot context came from' and clearly describes the optional query behavior. It is distinct enough for most selections, but it does not explicitly differentiate itself from sibling tools like context_info, so the differentiation is implicit rather than stated.

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 'Explain where Pilot context came from' gives an agent a clear reason to use this tool: when context provenance is needed. It also states the optional query branch, but it does not provide exclusions or point to alternatives, so usage guidance is clear but not fully elaborated.

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 read-only, non-destructive behavior. The description adds meaningful behavioral context: precedence is explicit, provenance is included, and runtime/system security is non-overridable. These details go beyond the basic safety hints.

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

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

Two sentences, front-loaded with the core purpose and then adding a key behavioral caveat. Every phrase earns its place with no redundant restatement of the tool name or schema fields.

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 enough for a read-only context-loading tool: it names sources, scope, precedence, provenance, and the security constraint. Since there is no output schema, the return format is not explicitly detailed, but the mention of 'merged context' and 'provenance' gives a sufficient picture.

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 parameters are already well documented. The description adds no param-specific detail beyond implying bounded source contents, which aligns with include_content and max_bytes_per_source. 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 clearly specifies the verb 'Load' and the resource: the effective ChatGPT Pilot context chain, naming the exact files involved (~/.pilot/GPT.md, AGENTS.md, GPT.md) and their precedence/provenance. This distinguishes it from generic file-reading siblings like read_file or project_snapshot.

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 about what this tool loads and that it is project-scoped, so an agent can tell when it is appropriate. It does not explicitly name exclusions or alternative sibling tools, but the context is clear enough for selection.

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 read-only/non-destructive behavior, and the description adds useful behavioral context: it returns capacity/free-space and enforces the machine access policy on the supplied path. It does not describe error behavior or return formatting, but this is minor for such a simple read tool.

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

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

A single sentence that front-loads the core behavior and then states the access constraint. No filler or redundancy.

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

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

For a one-parameter read-only tool with complete schema coverage and a readOnlyHint annotation, the description is almost sufficient. It would benefit from stating the output shape/units or handling of disallowed paths, but no output schema exists and the core semantics are clear.

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 input schema fully documents the path parameter, including relative-to-workspace-root and allowed absolute paths, so schema coverage is 100%. The description only restates that the path must be allowed by policy, adding little parametric meaning beyond the schema.

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

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

The description uses a specific verb ('Read') and names a concrete resource ('filesystem capacity and free-space information'), which clearly distinguishes it from sibling file/system tools like file_info or environment_info. The path scoping is also stated.

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 purpose implies when to use it—when filesystem capacity/free space for a path is needed—but it does not explicitly state when to prefer this over alternatives or mention any sibling tools. No exclusions or alternative routing are provided.

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

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

Beyond the destructiveHint annotation, the description adds valuable behavior: array edits are validated in memory and written atomically, so a failed edit never leaves a partial file. It also clarifies that the file must already exist and be UTF-8 encoded. There is no contradiction with 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 tight sentences with no filler. The purpose is front-loaded, and the important atomicity caveat is placed immediately after the mode description.

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

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

For an 8-parameter mutation tool, the description is complete enough: it identifies the file scope, conditions, modes, and the key safety behavior. Parameter details are fully covered by the schema, and there is no output schema requiring return-value documentation. A brief comparison with sibling tools would make it fully complete.

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

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

Schema coverage is 100%, providing a strong baseline. The description adds meaning by making the either/or relationship between old_text/new_text and the edits array explicit, and by characterizing the array as transactional, which is not readily apparent from individual schema fields.

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 clear verb and resource: 'Replace exact text in an existing UTF-8 file.' It also conveys the two invocation modes, which helps separate it from broader file tools, though it does not explicitly name sibling alternatives.

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

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

The description implies when to use the tool ('Replace exact text in an existing UTF-8 file') and explains the two input modes. It does not provide explicit when-not-to-use guidance or compare with overlapping siblings such as update_file or apply_patch.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavior beyond that: secret-like variables are always redacted, and values are only included when explicitly requested for non-sensitive variables.

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 primary action is front-loaded ('List environment variable names'), and the key redaction caveat is included compactly.

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, the description and schema together cover names, optional values, redaction, and filtering. No output schema exists, but the return concept is clear enough; minor gaps like exact filter matching semantics are acceptable at this complexity level.

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 filter and include_values are already documented. The description adds value by clarifying that secret-like variables are redacted even when include_values is true, which is an edge-behavior the schema alone does not fully convey.

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 and resource: 'List environment variable names' and optionally non-sensitive values. This clearly distinguishes it from sibling tools like system_info or machine_status, and the redaction mention adds precision.

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

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

The description implies the tool is for inspecting environment variables, but it does not explicitly state when to prefer it over alternatives such as shell_command or when not to use it. No exclusions or alternative routing is provided.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, covering the risk profile. The description adds meaningful behavioral context beyond annotations: there is no shell parsing or quoting, and arguments are passed as an argv vector, which affects how commands are interpreted.

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 wasted words. The core execution model is front-loaded, and the sibling-tool routing is placed in the second sentence. Every phrase adds value.

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

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

The tool is open-world and destructive with 8 parameters and no output schema, but the description focuses mainly on tool selection and execution style. It does not clarify whether execution is synchronous, whether output is returned, or how timeouts/exit codes behave. However, the params imply a synchronous run with captured output, so the core guidance is still adequate.

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 75%, so most parameters already have documented meaning. The description's emphasis on 'explicit argv vector' reinforces the args parameter but adds little per-parameter detail beyond the schema. It does not compensate for the few undocumented parameters, but the high schema coverage supports the baseline score.

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 action, 'Execute one binary', with an explicit argv vector and no shell parsing or quoting. It also names the key sibling, shell_command, and contrasts against it, so an agent can differentiate the tools immediately.

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 guidance: prefer this tool over shell_command for scripts, Git helpers, and structured command invocation. This gives a clear selection rule rather than leaving the agent to infer when the tool is appropriate.

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 the description only needs to add behavior beyond safety. It does by specifying that the SHA-256 hash is optional and limited to regular files, which is useful for setting expectations.

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 entire description is one front-loaded sentence with no filler. Every part contributes to understanding the tool's purpose and scope.

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

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

With no output schema, the description does not explain what metadata fields are returned, which could leave an agent guessing about the response shape. For such a small tool, however, the path and hash parameters are fully covered, so the gap is moderate rather than severe.

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 input schema already describes all parameters with 100% coverage, including path constraints and the include_hash default. The description's 'optional SHA-256 hash for regular files' mostly restates the schema's include_hash description, adding no significant new 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 ('Get') and resource ('file or directory metadata'), plus the optional SHA-256 hash. This clearly separates it from content-reading siblings like read_file and listing tools like list_directory.

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 metadata-and-hash scope gives a clear context for when the tool is appropriate, while the read-only annotations reinforce safe use. It does not explicitly name sibling alternatives or exclusions, but the intended use is clear for a metadata lookup.

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. The description adds meaningful behavioral context beyond that: build and dependency directories are skipped by default, and include_ignored re-enables them. This is genuinely useful for predicting tool 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?

Two sentences with no filler. The primary action is front-loaded, and the important default-skipping behavior is stated immediately and compactly.

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 search tool with 100% schema coverage, the description captures the essential behavior and default exceptions. It does not describe return value shape or pagination, but the tool's purpose makes the result type reasonably inferable.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description only references include_ignored, adding little beyond the schema. 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?

Description states a specific verb ('Find'), resource ('files'), and method ('recursively by glob'), which clearly differentiates it from sibling tools like list_directory and search_code. The skipping behavior further clarifies what this tool is specialized for.

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: use when you need recursive file discovery by glob pattern, not directory listing or content search. It does not explicitly name alternatives or exclusions, but the recursive-glob framing is enough to infer appropriate usage.

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 the operation is destructive/mutating, so the description doesn't need to repeat that. It adds a useful behavioral detail—'without shell interpolation'—but doesn't disclose further effects such as whether the working tree changes or whether staging can be undone. No contradiction with 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?

The entire description is one short, front-loaded sentence. It places the action and object first and adds the distinguishing mechanism at the end without any 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?

This is a simple two-parameter tool with a fully described schema, so the description plus schema are largely sufficient. It could mention that this only stages files and does not commit, but that is reasonably inferable from the tool name and sibling git_commit.

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 goes beyond the schema by saying paths are 'explicit' and that no shell interpolation is applied, which tells the agent the paths are treated literally and glob patterns won't be expanded.

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 starts with a specific verb, 'Stage,' and a precise resource, 'explicit repository paths.' It also distinguishes itself from shell-based alternatives by saying 'using Git directly, without shell interpolation,' making its role clear relative to the shell_command sibling.

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

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

The phrase 'without shell interpolation' signals a clear context: use this when you want to stage paths directly via Git without shell expansion. It doesn't explicitly name alternative tools or state when not to use them, but the contrast with shell_command is implied well enough.

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 useful scope information (local vs optional remote) and the presence of current/upstream metadata, but does not describe output format, pagination, or error behavior. This is acceptable given the simple read-only nature of the tool.

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

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

The description is a single sentence with no filler, front-loading the core action and resource. It conveys the important optional behavior ('optionally remote branches') concisely and is easy to parse.

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 listing tool with two optional parameters and no output schema, the description covers the essential behavior and what metadata is returned. The main gap is a precise description of the output format, but the description provides enough for an agent to call the tool correctly.

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

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

The input schema already covers both parameters fully with descriptions: 'all' means include remote branches, and 'path' defaults to the workspace. The description's phrase 'optionally remote branches' reinforces the 'all' parameter but does not add substantial meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description names a specific verb ('List'), resource ('Git branches'), and scope ('local' and optionally 'remote'), plus the metadata returned ('current/upstream'). This clearly distinguishes it from sibling git tools such as git_log, git_status, or git_diff, which operate on commits or working-tree 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 description clearly conveys when this tool is appropriate: to list branches, including remote ones when requested. It does not explicitly name alternatives or exclusion criteria, but the tool's purpose is unambiguous enough that an agent can select it over the listed git siblings without confusion.

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 mark `destructiveHint: true`, and the description adds a specific safety limitation: force/discard modes are intentionally not exposed, so the agent can expect failures rather than destructive overwrites. This is valuable context beyond the generic annotation and does not contradict it.

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

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

Two concise sentences, with the core action front-loaded and the safety limitation in a single clause. Every word earns its place; no fluff 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?

For a simple 3-parameter tool, the description covers the core action and an important behavioral guardrail. It doesn't describe return output or failure modes, but no output schema exists and git checkout behavior is standard. A mention of uncommitted changes would make it fully complete, but it's already largely sufficient.

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

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

Schema description coverage is only 33% (only `path` is described). The description compensates by naming `branch` as the target and explaining `create` through 'create and switch to a new branch.' It doesn't detail the `create` boolean's default or behavior when false, but it adds meaning beyond the schema.

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

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

States a clear verb ('Switch') and resource ('Git branch'), explicitly covering two modes: switching to an existing branch and creating a new one. It distinguishes itself from sibling `git_branch` by describing the act of switching. The note about force/discard modes sharpens the scope.

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

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

The description implies when to use the tool (when changing branches) but does not mention alternatives or exclusions. Unlike a stronger definition, it doesn't name a sibling tool or state when not to use it. The only limitation is about force/discard modes, not about choosing between 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 already mark the tool as write/destructive, and the description adds that the commit is local and only uses staged changes unless --all is used. It does not mention failure modes like missing git identity or 'nothing to commit', but given the annotation coverage, this is acceptable.

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-structured sentence that front-loads the action and resource, then adds the optional flag behavior. Every word earns its place with no redundancy 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?

The core behavior, local scope, and staging precondition are all covered, and the schema provides all parameter details. It does not describe post-commit effects or verification steps, but these are not essential for basic 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%, so the schema already documents all parameters. The description restates the --all behavior but adds no extra semantic meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description names a specific verb ('Create') and resource ('local Git commit') and disambiguously distinguishes the too from siblings like git_push and git_add by specifying that it operates locally and from staged changes. It is fully aligned with the tool's name and 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 gives clear context: use this when you have staged changes and want a local commit, and it explains the optional --all behavior for staging tracked modifications. It does not explicitly mention alternatives, but the context is strong enough for an agent to select it.

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

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

Annotations already signal destructiveness, and the description adds meaningful behavioral detail: it verifies, stages only the requested paths, creates a local commit, and refuses pre-existing staged changes. It does not detail what verification commands run or cleanup behavior, but the guardrail disclosure exceeds what annotations 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, both information-dense, with the key scope constraint and refusal guardrail front-loaded. There is no 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?

For a destructive six-parameter tool, the description covers the core workflow and the most important guardrail, and the high schema coverage covers parameter details. It could be more complete by describing what happens after verification or on failure, but it is sufficient for deciding to call the tool.

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

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

Schema description coverage is 100%, so the baseline for this dimension is satisfied. The description adds little parameter-specific meaning beyond the schema; 'explicit paths' and 'local commit' are behavioral clarifications rather than new parameter semantics.

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

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

The description opens with three specific actions — verify, stage explicit paths, and create a local commit — and the final clause 'Refuses pre-existing staged changes' distinguishes it from plain git_commit. This lets an agent understand exactly what the tool does without inspecting 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 clear use context: commit only explicitly listed paths and only when there are no pre-existing staged changes, which also acts as a when-not condition. It does not name alternative tools like git_commit or git_add or state when verification is unnecessary, so it stops short of fully explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the implementation detail that no shell command is executed, which is minor but useful. It does not describe output shape, truncation, or size limits, though these are partly reflected in the schema.

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

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

One front-loaded sentence with no filler. Every element earns its place: the read behavior, the working-tree/staged distinction, the no-shell-command note, and optional path scoping.

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 Git diff tool with well-documented optional parameters and safety annotations, the description is largely complete. It could mention the output format or default behavior when no paths are given, but those are inferable from the tool name and 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 documentation coverage is 100%, so the baseline is 3. The description reinforces the meaning of 'staged' and 'paths' but does not add semantic detail beyond what the input schema already provides for the six parameters.

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

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

The description states a specific verb ('Read'), a precise resource ('Git working-tree or staged diff'), and an optional scoping behavior ('limited to specific paths'). It clearly identifies this as the diff-reading tool among siblings like git_status and git_show, and conveys that it does not invoke a shell command.

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 usage context: it reads working-tree or staged diffs and can be scoped to paths. It implicitly contrasts with shell_command by noting it runs without a shell command, though it does not explicitly describe when to prefer alternative Git tools or shell commands.

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. The description adds valuable behavioral context with 'without shell interpolation,' signaling that no shell command execution or injection risk is involved. This goes beyond the structured 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?

The description is a single, front-loaded sentence with no filler. Every word contributes: the action, the resource, the output nature, and the safety-relevant execution detail.

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

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

For a low-complexity, read-only tool with fully documented optional parameters, the description is nearly complete. It does not detail the exact structured return fields, and no output schema exists, so a small gap remains; however, 'structured Git commit history' plus schema and annotations covers all essential call-time needs.

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 descriptions for ref, path, and max_count including defaults. The tool description does not add parameter-specific meaning, but the schema already carries the full burden, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Read structured Git commit history.' This clearly distinguishes it from sibling tools that show diffs, branches, or add/commit changes, and 'structured' indicates the output form.

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 intended use is implied as 'read Git commit history,' but the description does not explicitly say when to prefer this over git_show, git_diff, or git_branch, nor does it provide exclusions or alternative routing. It is adequate but leaves usage decisions to inference.

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

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

Beyond the annotations, the description richly discloses the workflow: fetching the remote branch, refusing selected-path drift, copying files into an isolated worktree, optional verification, committing, and pushing. It explicitly states that the caller worktree/index/branch remain unchanged, which is crucial behavioral context for a destructive-flagged tool.

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

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

The description is two sentences with no filler. The core purpose is front-loaded, and the following workflow sentence packs every important behavioral guarantee into a compact list of actions.

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 covers the full operational sequence and key safety guarantees, and the schema fully documents the 7 parameters. Since there is no output schema, a brief note on expected result/return shape would make it more complete, but the description is already sufficient 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%, so the schema already documents each parameter. The description adds general workflow context, such as 'only those files' and 'optional verification,' but it does not add much parameter-specific meaning beyond what the schema provides. 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 opens with a specific verb and resource: 'Safely publish only selected files.' It also clarifies the precise scope (only selected paths) and the isolation mechanism, which clearly differentiates it from broader siblings like git_push or git_commit.

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 makes the intended use case clear: publishing only selected files while avoiding changes to the caller's worktree. It does not explicitly name sibling alternatives or state when not to use it, but the context is strong enough for an agent to infer appropriate use.

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 adds meaningful behavioral context by noting that this is an 'external mutation' and 'approval-gated by the developer policy', complementing annotations that already indicate readOnlyHint=false, destructiveHint=true, and openWorldHint=true. It does not detail consequences on the remote, but the annotations already cover the destructive profile.

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

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

Two short sentences with the core purpose front-loaded and the policy caveat cleanly separated. There is no filler, redundancy, or unnecessary detail.

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

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

The description covers the critical safety context (external mutation, approval gate), and the schema provides defaults for the optional parameters. However, it omits behavior around conflicts, force-pushing, or expected output, leaving some operational details to inference.

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 description provides no parameter-level information. The schema documents path, branch, and remote, but set_upstream is left undocumented (75% coverage), and the description does nothing to clarify this boolean flag or any parameter interplay.

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 ('Push a Git branch to a remote'), which clearly communicates the operation. It also distinguishes itself from sibling Git tools like git_commit and git_checkout by focusing on the push action.

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

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

No guidance is given about when to use this tool versus alternatives or what preconditions must be met. The approval-gating note is a policy warning, not usage direction, and no sibling tool is mentioned as 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 declare readOnlyHint=true and destructiveHint=false, and the description aligns with that. It adds meaningful behavioral context by disclosing that refresh=true performs a fetch first, which is a non-destructive side effect beyond what the annotations state.

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 the core purpose front-loaded and the optional-refresh explanation following immediately. Every sentence adds value 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 read-only status tool with no required parameters and no output schema, the description covers the main behavior and the one non-default option. It does not describe the exact return format, but the ahead/behind status is strongly implied by 'local-vs-remote branch state.'

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 input schema already documents all four parameters with 100% coverage, so the baseline applies. The description clarifies why refresh=true is useful (current remote state), but this largely restates the schema's refresh description rather than adding substantial new 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 uses a specific verb ('Read') and a precise object ('local-vs-remote branch state'), making the tool's function unmistakable. It also distinguishes the tool from siblings like git_status by focusing on the remote comparison rather than working-tree status.

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

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

The description implies when to use the tool—whenever local branch state must be compared to remote state—and gives a concrete parameter-level guideline for refresh=true. However, it never names alternative tools or states when not to use this one, so selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful 'bounded output' behavior tied to max_bytes, but it does not disclose details like what happens when max_bytes is exceeded or the exact output format. This is acceptable given the read-only annotations but not especially rich.

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 a single, focused sentence with no filler. The main verb and resource are front-loaded, and every word adds meaning. It is appropriately sized for the tool's complexity.

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 four optional parameters and no output schema, the description covers the core invocation context: what is read, what output to expect, and that output is bounded. Minor gaps remain around exact return formatting and truncation behavior, but these are not critical for selecting and invoking the 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?

With only 50% schema description coverage, max_bytes and stat_only lack direct schema documentation. The description partially compensates by indicating 'bounded output' for max_bytes and 'patch or statistics' for stat_only. However, it does not fully explain the behavior or defaults of these parameters.

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

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

The description states a specific verb ('Read'), a clear resource ('one Git revision'), and the output content ('patch or statistics'). This distinguishes it from sibling tools like git_log, git_diff, and git_status, which handle history listing or comparisons.

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

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

The description implies the tool is for inspecting a single revision's patch or stats, which gives some context for when to use it. However, it does not explicitly mention alternatives like git_diff for comparing revisions or git_log for browsing history, so routing to the right sibling is left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral nuance by stating it works without running a shell command, but it does not disclose any additional edge-case behavior or output characteristics beyond that.

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 a single, well-structured sentence that front-loads the action and resource. Every word earns its place, with no fluff or repetition of schema fields.

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 one-parameter read-only tool, the description adequately explains what will be read: branch, upstream tracking state, and working-tree status. Since there is no output schema, a slightly more detailed note about the returned value format would make it fully complete, but the current description is sufficient for an agent 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?

The input schema already documents the only parameter (path) with a full description including the default behavior. The tool description adds no parameter-specific details beyond confirming the repository context, so with 100% schema coverage the baseline of 3 is appropriate.

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

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

Description uses a specific verb ('Read') and names the precise resource: current Git branch, upstream tracking state, and working-tree status. This clearly distinguishes it from sibling tools like git_diff, git_log, and git_branch, while the phrase 'without running a shell command' also separates it from shell_command.

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 provides useful context that this tool is a safe, direct way to inspect repository state rather than invoking a shell command. However, it does not explicitly state when to choose this over sibling tools such as git_branch or git_status alternatives, leaving some routing decisions to the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds value by specifying exactly what will be returned: dimensions, size, and SHA-256. This makes the tool's behavior predictable without overclaiming. Minor omitted details like error behavior for unsupported formats are not critical given the simple scope.

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, tightly constructed sentence states the operation, accepted formats, and expected return values with no filler. Every element earns its place and the key purpose is front-loaded.

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, single-parameter inspection tool, the description plus annotations cover the safety profile and return content. There is no output schema, so the description's mention of returned dimensions, size, and SHA-256 is necessary and sufficient. Slightly more detail about unsupported formats or error handling would push this to 5, but it is already complete enough.

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% for the single path parameter, including workspace-relative and absolute path semantics. The description does not add further parameter detail, but the schema already fully carries that burden, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb ('Inspect'), the resource ('local PNG, JPEG, or WebP image'), and the outputs ('dimensions, size, and SHA-256'). It also distinguishes this tool from generic siblings like file_info by scoping it to image files and their specific metadata.

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

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

The description implies usage: local image files in supported formats. However, it does not explicitly state when not to use it, such as for non-image files, nor does it mention alternatives like file_info or read_file for other cases. Context is clear but exclusions or sibling routing are absent.

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, and the description's 'Inspect' is consistent with a read-only operation. It adds useful context about the contents of returned observations, but does not disclose ordering, pagination, or any additional behavioral details. No contradiction exists.

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 a single sentence front-loaded with the verb and resource, with no filler. Each listed item earns its place and partially compensates for the missing output schema.

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

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

For a read-only listing with optional filters and no output schema, the description is incomplete: it does not state what 'bounded' means, what limit bounds, how status and target filters behave, or how results are ordered. The enums in the schema help, but parameter semantics and behavioral details remain ambiguous.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining limit, status, and target. It mentions 'target' and 'promotion status' as output fields, weakly hinting at two filters, but never explains the limit parameter, the meaning of the enums, or that these values act as filters. An agent cannot reliably infer parameter semantics.

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

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

The description opens with the specific verb 'Inspect' and names the resource ('learning observations and candidates'), then lists the returned aspects: evidence, target, confidence, and promotion status. This makes it clearly distinguishable from mutating siblings like learning_promote and learning_rollback, and from learning_observe.

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

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

No guidance is given on when to use learning_history versus learning_observe, learning_promote, or learning_rollback. The description only states what the tool does, not when it should be chosen or when an alternative is more appropriate.

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 establish it is not read-only but not destructive; the description adds the crucial boundary that it never changes Skills, Capabilities, GPT.md, or memory by itself. This prevents agents from assuming recording lessons has immediate side effects on knowledge artifacts, though it still doesn't say where the record is persisted.

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 focused sentences with no filler: the action is front-loaded and the boundary condition is stated immediately after. 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?

Given seven parameters, a nested lessons object, no output schema, and no per-parameter descriptions, the brief description leaves meaningful gaps: how lessons should be structured and scored, whether todo_id links to TODO tracking, and what happens after recording. It is not complete enough for an agent to use all fields confidently.

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 description gives semantic meaning to the core parameters: task, outcome, evidence ('evidence-backed'), and lessons ('learning candidates'), and the target enum values are reflected in the list 'Skills, Capabilities, GPT.md, or memory'. However, confidence, reuse_potential, summary, todo_id, and skills_used remain unexplained, and schema coverage is 0%, so the description only partially compensates.

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

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

States a specific action (Record) on specific resources (evidence-backed task outcome and reusable learning candidates), and the second sentence scopes it as observation-only, distinguishing it from promotion tools like learning_promote. An agent can infer what this tool produces 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?

The description implies the tool is for recording observations rather than applying changes, and 'by itself' hints that promotion is a separate step. However, it never names alternatives such as learning_promote or states when to choose this tool over learning_history or other learning-related 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 only indicate the tool is not read-only and not destructive. The description adds meaningful behavioral detail: memory lessons are written to the lessons drawer, while Skill/Capability/GPT targets become proposals and never silently modify Pilot. This goes beyond the annotation flags to clarify how state may change.

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 wasted words: the main action is front-loaded, followed by the key side-effect caveat. It is appropriately sized for a tool with one parameter.

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 covers purpose and side effects well for a simple, single-parameter tool with no output schema. It is slightly incomplete because 'evidence-backed' is left undefined and it does not specify how promotion is realized beyond the side-effect statement.

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 for documenting candidate_id. It only implies candidate_id is the identifier of the evidence-backed candidate, without stating where the ID comes from or its format. For a single, self-named parameter this is a minor but real 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?

The description states a specific action ('Promote') on a clear resource ('one evidence-backed learning candidate') and explains the outcome for different target types. This distinguishes it from siblings like learning_rollback and learning_observe, which clearly serve different purposes.

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 'evidence-backed learning candidate' implies a prerequisite for use, but the description does not explicitly say when to use this tool versus alternatives. It does not name learning_observe or learning_history as sources of candidates, nor learning_rollback as the reversal tool.

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

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

The annotations already mark the tool as destructive, and the description adds valuable context by guaranteeing that code, skills, capabilities, and GPT.md are not modified. It also clarifies that the affected state is memory-related, which goes beyond 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?

The description is two sentences, front-loaded with the core action, and the safety caveat is a meaningful addition rather than filler. It is concise without sacrificing the most important behavioral constraint.

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 operation is simple and the annotations cover the destructive profile, so the description is mostly sufficient for safe invocation. However, it leaves the source and meaning of candidate_id ambiguous and does not describe return behavior, which is more noticeable because there is no 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?

The schema defines candidate_id as a required string but provides no explanation, and the description does not map this parameter to a learning proposal or promoted lesson ID. With 0% schema description coverage, the description needed to clarify what candidate_id refers to and whether it distinguishes the two rollback/removal modes.

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: 'roll back a learning proposal or remove a previously promoted memory lesson.' It also draws a clear boundary by saying Code, Skills, Capabilities, and GPT.md are never modified, which helps distinguish it from tools like self_update or apply_patch.

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 intended use is implied by the two actions (undoing a proposal or removing a promoted lesson), but the description never explicitly explains when to prefer this tool over related siblings like learning_promote or learning_history. It does not name alternatives or state conditions where rollback should not be used.

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 this as read-only and non-destructive. The description adds useful behavioral context beyond those annotations by specifying that it returns files, directories, symlinks, size, and modification time, and that it does not execute a shell command. No contradiction with annotations exists.

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 a single, tightly worded sentence that front-loads the core action and resource. It includes the most important differentiator ('without running a shell command') without any wasted words.

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 listing tool with fully documented optional parameters and read-only annotations. The description sufficiently covers what the tool returns (files, directories, symlinks, size, modification time) and why it should be used over a shell command, so the agent has enough information 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?

The input schema already provides 100% parameter documentation, covering path, max_entries, and include_hidden with descriptions and defaults. The tool description does not add any additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('files, directories, and symlinks'), and adds distinguishing details like size and modification time. It also explicitly differentiates itself from shell-based approaches, making it easy for an agent to understand what this tool does.

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 'without running a shell command' gives clear context for when to prefer this tool over shell_command. It doesn't explicitly name other alternatives like find_files, but the listing scope and metadata details make the intended use case 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, so the safety profile is covered. The description adds that it targets local endpoints and includes owning PIDs, but it doesn't disclose platform dependencies, potential latency, or output volume controls beyond the limit parameter.

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-structured sentence that front-loads the core function and immediately mentions the optional filters. There is no redundant wording or filler, making it highly efficient for an agent to parse.

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 list tool with no output schema, the description states what is returned (endpoints and PIDs) and the main filtering dimensions. It lacks detail on the meaning of limit and exact output format, but these are minor given the simple nature of the operation and the strong 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. It does map port, PID, and protocol to 'filtered by', adding meaning beyond raw parameter names, but it omits the limit parameter entirely, leaving its purpose unstated.

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

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

The description uses a specific verb ('List') with a concrete resource ('local TCP/UDP endpoints and owning PIDs') and names the optional filters. This clearly distinguishes it from siblings like list_processes or network_info 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?

The description gives no guidance on when to use this tool versus alternatives such as network_info or list_processes. It states the core action but provides no exclusions or explicit use cases, leaving the agent to infer when this is the right 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read profile is covered. The description adds 'bounded structured results,' which gives some behavioral context about output shape and size limits, but it does not disclose details like exact returned fields, ordering, or whether the process list is a snapshot. There is no contradiction with 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?

The description is a single front-loaded sentence with no wasted words. It clearly states the action and a key behavioral qualifier, though 'bounded structured results' is a little vague and could have been slightly more specific without harming brevity.

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 list operation with fully documented parameters and safety annotations, the description is mostly sufficient. However, there is no output schema and the description does not specify what fields the returned process objects contain (e.g., PID, name, CPU), which is a meaningful gap for an agent that needs to act on the results.

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 both 'limit' and 'filter' are already documented with type, bounds, default, and case-insensitivity. The description adds no further parameter-level meaning beyond summarizing the result as bounded, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb ('List'), resource ('operating-system processes'), and a scope modifier ('bounded structured results'), so it is clear what the tool does. It does not explicitly name a sibling to differentiate it from, but the verb and resource are unambiguous enough to separate it from process_status, start_process, and stop_process.

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

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

The description implies usage whenever an agent needs to see current OS processes because of the clear 'List' verb. However, it gives no explicit guidance about when to prefer this over sibling tools like process_status, start_process, or stop_process, and it does not state any exclusions or limitations.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds valuable context by stating this is the 'high-authority routing path' while noting the remote machine still enforces its own policy, workspace boundary, approvals, and audit log. This helps an agent understand the authority and safety envelope beyond the annotation flags alone.

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 tight sentences with no filler: the first states the action and target, and the second adds essential authority and safety context. It 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 generic remote tool-call router, the description gives enough for a basic invocation but leaves gaps: no guidance on argument shape, timeout semantics, or the returned payload. The lack of an output schema raises the burden on the description, which is only partially met.

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, but it only implicitly maps 'one MCP tool' to the 'tool' parameter and 'registered remote machine' to 'machine.' It does not explain 'arguments,' how to construct the nested object, or the meaning and default behavior of 'timeout_ms.'

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 and resource: 'Run one MCP tool on a registered remote machine.' It clearly communicates what the tool does, but it does not explicitly name or contrast sibling tools such as machine_read, machine_tools, or runtime_exec, so it does not fully earn a 5.

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

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

The intended use is implied by the phrasing 'Run one MCP tool on a registered remote machine,' so an agent can infer when to select this tool. However, there is no explicit guidance about when not to use it or which alternative to prefer, such as machine_read for reads or shell_command for local commands.

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 the safety profile is covered. The description adds little behavioral context beyond purpose—no mention of network probe behavior, failure modes, or timeout effects—but it does not contradict 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?

A single sentence front-loads the core action and scope before enumerating accepted selectors. Every element contributes to selecting or invoking the tool; 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 simple two-parameter read-only probe, the description identifies the target, the operation, and the selector format. It does not specify the output shape or the default timeout, but the term 'health and latency' provides adequate expectation, and no output schema exists to fill the 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?

With schema description coverage at 0%, the description usefully explains that 'machine' can be an id, name, hostname, alias, IP address, or host:port. The optional timeout_ms is not described textually, but its name and min/max bounds carry most of the 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 states a clear action ('check health and latency') and a precisely scoped resource ('one registered remote machine'), with a detailed selection criteria list. It is specific enough to be usable, but it does not explicitly differentiate from the closely named sibling machine_status, which could overlap on health reporting.

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

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

The description implies when to use this tool: when a single registered remote machine needs health/latency checking. It does not state exclusions or point to alternative tools such as machine_status, machines_list, or machine_read, so an agent has to infer the routing decision.

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. The description goes beyond by explaining the gateway verification and fail-closed behavior, and by disclosing that mutating or unannotated remote tools are rejected. This adds meaningful operational context beyond 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 sentences, no filler. The main purpose is front-loaded, followed by a crisp routing rule for the alternative. 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?

The description fully addresses the when-to-use decision and the security guardrail, but it leaves parameter semantics and invocation details entirely to inference. Given no output schema and 0% schema description coverage, this is adequate for selecting the tool but not fully complete for constructing a correct call without additional 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 description coverage is 0%, and the description does not explain machine, tool, arguments, or timeout_ms. While parameter names are somewhat self-explanatory, no parameter-level meaning is provided to compensate for the lack of schema descriptions.

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 action (run a remote MCP tool) with a clear prerequisite. It also distinguishes itself from machine_call by defining which tools are handled here versus there, so the agent can tell them apart immediately.

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 guidance is given: use this tool only when the remote tool declares readOnlyHint=true, otherwise use machine_call. This directly names the alternative and the condition for choosing it.

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

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

Annotations already mark the tool read-only and non-destructive. The description adds a behavioral guarantee beyond those hints: it never contacts remote machines, which has latency and side-effect implications. This is useful additional transparency, though it does not describe output shape or edge cases.

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

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

Three short sentences, front-loaded with the action, then two clarifying facts. Every sentence earns its place and there is no filler or repetition of 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?

For a zero-parameter, read-only list tool without an output schema, the description is complete: it states what is returned (registered remote machines), that no remote contact is made, and what selectors apply to the machines. No critical context appears 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 input schema defines zero parameters, so the baseline for this dimension is 4; there is no undocumented parameter burden. The mention of selectors (id, name, hostname, alias, IP, host:port) is identity/context information rather than parameter documentation, but it still adds helpful meaning beyond the empty schema.

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

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

Opens with a specific verb and resource: 'List registered remote machines.' The final sentence clarifies the operation is local-only ('does not contact remote machines'), which distinguishes it from interacting or probing tools like machine_status or machine_probe. The selector list adds context without blurring 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 'does not contact remote machines' statement gives a clear, safe-use context: use this when you need the registry of machines without triggering network activity. It does not explicitly name alternatives or exclusion cases, so it falls short of a 5, but 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, so the safety profile is covered. The description adds useful nuance by noting the tool returns a compact summary by default and that deeper detail should be opt-in, implying cost or noise concerns. No annotation contradiction exists.

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 delivers the purpose first, then usage guidance, with no filler or repetition of the tool name. 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 two optional parameters, no required inputs, and annotations covering safety, the description is nearly complete. It lacks explicit detail about the default output structure, but the phrase 'compact machine/runtime health summary' gives an agent enough context to call it appropriately.

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 both include and detailed are already documented in the schema. The description adds the 'deeper diagnostics' framing for detailed=true but does not explain the meaning of the enum values in include, which the schema already handles. 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 ('Return') and resource ('compact machine/runtime health summary'), making the core purpose clear. It does not explicitly differentiate itself from sibling tools like runtime_info or system_info, but the 'health summary' framing provides enough distinct identity.

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 guidance on when to request optional sections or detailed=true ('only when deeper diagnostics are needed'), implying that the default compact call is preferred. However, it does not explain when to choose this tool over siblings such as runtime_info, process_status, or system_info.

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

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

The annotations already indicate read-only, non-destructive, open-world behavior, and the description adds useful caching specifics: 60-second cache lifetime and replacement on fingerprint change. This is meaningful behavioral context beyond what the annotations alone convey.

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

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

Two sentences, no filler, with the core purpose front-loaded and caching behavior stated immediately after. 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?

The description is adequate for a simple read-only cached listing tool, but gaps remain: no return format, no explanation of timeout_ms, and no indication of when to choose this over sibling capability-related tools. Given there is no output schema, slightly more context about the returned capability list would improve 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 only 33%, so the description should compensate for undocumented parameters. It does clarify that 'machine' refers to a registered remote machine and that 'refresh' relates to the 60-second cache, but 'timeout_ms' remains entirely unexplained in both the schema and description.

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 the tool's action: list and cache tool capabilities exposed by one registered remote machine. It specifies a concrete resource ('tool capabilities' of a 'registered remote machine'), though it does not explicitly distinguish itself from sibling introspection tools like machine_probe or capability_diff.

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 provides no guidance on when to use this tool versus alternatives such as machine_probe, machine_read, or capability_diff. It implies the tool is for inspecting capabilities of a remote machine, but it does not state selection criteria, exclusions, or prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by explicitly stating there is no outbound network request. This adds meaningful behavioral context beyond the raw annotations and clarifies the tool's non-intrusive nature.

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 is front-loaded with the action and resource, then qualifies the behavior. Every word earns its place, with no redundancy or vague 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 parameterless read-only tool with strong annotations, the description is complete. It clearly tells the agent what the tool reads and what side effects it avoids, which is sufficient for correct selection and 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 tool has zero parameters, so parameter semantics are trivially satisfied. The description does not need to explain parameter meanings, and the schema is fully consistent with a parameterless tool.

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') and a specific resource ('local network-interface addresses and metadata'), making the tool's purpose unmistakable. It also distinguishes itself from tools like environment_info or system_info by clarifying its network-interface focus.

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 signals the intended use case: getting local network-interface information without triggering an outbound request. It does not explicitly name sibling alternatives or exclusion conditions, but the local-scope phrasing gives clear usage context.

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 the safety profile is covered. The description adds that the tool reports runtime and output offsets, giving some behavioral context, but does not disclose edge behaviors such as stale-PID handling (though the schema's process_id parameter hints at this). No contradiction with 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, front-loaded with the verb, with no filler. Every phrase conveys distinct information about the action and the returned data.

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 status tool with a simple two-parameter schema and no output schema, the description conveys the essential return fields (status, runtime, offsets) and the target resource. It could explicitly note that it does not return output content itself, but the word 'offsets' and the sibling read_process_output make that inferable.

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

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

Schema description coverage is 100%; both pid and process_id are already documented with references to start_process. The description does not add parameter-level meaning beyond the schema, so the baseline score of 3 applies.

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

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

States a specific verb ('Get'), resource ('managed background process'), and the exact data returned (status, runtime, current output offsets). This differentiates it from siblings like read_process_output (output content) and list_processes (system-wide listing) without needing to inspect their schemas.

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

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

The phrase 'managed background process' implies the intended context (processes started by start_process), and the listed return fields suggest when to call it. However, it does not explicitly name alternatives or state when not to use it (e.g., vs read_process_output or process_wait), so guidance remains implicit rather than explicit.

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

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

Annotations already mark the operation as read-only and non-destructive, and the description adds valuable behavioral nuance: a timeout does not stop the process, and the call returns exit code plus output offsets without polling. This goes beyond the structured metadata without contradicting it.

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

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

The entire description is one tight sentence that front-loads the core behavior and then adds the polling alternative and timeout side effect. No words are wasted.

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

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

The core call flow is understandable: wait, get exit code and output offsets, timeout without killing the process. However, with no output schema and several parameters undocumented, the description does not fully explain return value structure or the semantics of since_* offsets and output limits, leaving some ambiguity for advanced usage.

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 57%, covering pid, process_id, timeout_ms, and include_output; the description adds a little context with 'output offsets,' but since_stderr, since_stdout, and max_output_bytes remain unexplained. The description does not fully compensate for the undocumented parameters, though the main parameters are already well 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 names a specific verb and resource: wait on a managed background process. It also states the two terminal conditions (exit or timeout) and explicitly contrasts itself with repeated process_status calls, so the tool is clearly distinguishable from its closest sibling.

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

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

The description provides clear context: use this tool when you want to block until a background process exits or a timeout expires, avoiding repeated process_status polling. It does not explicitly enumerate when-not-to-use scenarios or name alternatives like read_process_output, but the guidance is reasonably 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 show destructiveHint=true, so the mutation is expected. The description adds valuable behavioral context by explaining the restriction on recovered processes and the requirement that the process be live. This goes beyond what the annotations alone reveal.

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 focused sentences: the first states the core operation, the second provides an important limitation. No filler or redundant repetition of schema details.

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 mutating tool with complete parameter documentation and destructive annotation, the description effectively communicates the core behavior and key edge case (recovered processes). It does not describe return values, but no output schema exists and the essential invocation context is present.

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 input schema already documents all parameters including pid, input, end, and process_id. The description reinforces that input is UTF-8 text but adds no significant parameter-level meaning beyond the schema.

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

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

The description uses a specific verb and resource: 'Write UTF-8 text to the standard input of a live process started by start_process.' This clearly distinguishes the tool from siblings like read_process_output, process_status, and exec_process. The target resource and action are 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?

The description clearly scopes the tool to live processes started by start_process, and explicitly warns that recovered processes cannot have stdin reattached. This gives useful context for when to use the tool, though it does not explicitly name alternatives or state when not to use it beyond the recovery caveat.

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 read-only and non-destructive behavior. The description adds useful behavioral context by defining the snapshot as 'bounded' and by specifying exactly which data sources are read. This aligns with readOnlyHint=true and gives the agent a clear picture of the tool's scope without contradicting 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?

The description is a single well-constructed sentence that front-loads the action and scope, then efficiently lists the snapshot components. Every clause adds information; there is no filler or redundant restating of the tool name.

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

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

For an optional-parameter read-only tool with no output schema, the description sufficiently explains what the tool returns by naming each snapshot section. Together with the fully documented input schema and safety annotations, the agent has everything needed 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%, with each parameter already documented with defaults and types. The description adds general context about snapshot content but does not materially deepen the meaning of path, include, or max_tree_entries beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Read') with a specific resource ('bounded coding-oriented project snapshot') and enumerates the concrete contents included: Git status, top-level tree, package/scripts, project type hints, instruction files, and Pilot GPT.md provenance. This clearly distinguishes it from granular sibling tools like git_status, read_files, or list_directory.

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 'in one call' implies the tool is meant for efficient project-wide orientation, and the enumerated sections suggest when it is useful. However, it does not explicitly name alternatives or state when to prefer a granular sibling like git_status or read_files instead, leaving usage boundaries 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 and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail: it returns the file SHA-256 to detect concurrent changes, and it enforces line/byte limits. This goes beyond the annotations without contradicting them.

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 the core action front-loaded and the important SHA-256 workflow placed second. Every sentence earns its place; there is no filler or redundancy.

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 tool with fully documented parameters, the description covers the main return value, the SHA-256, and the concurrency use case. Since there is no output schema, more detail about the exact response format or defaults could be helpful, but the essentials are present.

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 in the schema with meaningful descriptions. The tool description adds no parameter-specific semantics beyond the general mention of line and byte limits, which matches the baseline of 3.

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 states the tool reads a UTF-8 text file, with specific constraints on line and byte limits. This distinguishes it from sibling tools like file_info or list_directory, which inspect metadata or directory entries rather than file contents.

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 for when to use this tool: whenever file content needs to be read. It also adds a concrete workflow hint, passing the returned SHA-256 back as expected_sha256 during writes, which helps coordinate with write_file. It does not explicitly name alternatives or exclusion cases, so it stops short of a 5.

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

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

Annotations already mark it read-only and non-destructive; the description adds concrete behavior beyond that: UTF-8 restriction, per-file line/byte limits, SHA-256 hashing, and per-file failure reporting. It does not detail the full response structure, but the safety profile is already covered by 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 sentences, with the core operation front-loaded in the first sentence and every clause earning its place. The second sentence provides per-file behavior without redundancy.

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 tool with a moderately nested input schema and no output schema, the description covers the main selection criteria, encoding, limits, hashing, and failure isolation. It could add an explicit statement of the response shape, but an agent can safely invoke it from this plus the schema.

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

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

Top-level schema coverage is only 50%, and nested fields like max_bytes, max_lines, start_line, and line_numbers lack schema descriptions. The description partially compensates by explaining per-file line/byte limits and per-file failures, but it does not clarify start_line or line_numbers semantics.

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

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

The description opens with a specific verb and resource: 'Read multiple UTF-8 text files in one bounded call.' The plural 'files' and 'one bounded call' clearly distinguish it from the singular sibling read_file, making tool selection obvious.

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 conveys a batching use case ('multiple files in one bounded call') and per-file failure isolation, which signals when to prefer this over repeated read_file calls. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral detail: that passing since_stdout/since_stderr yields only new output and that wait_ms blocks until output arrives or the process exits. This goes beyond schema and 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 sentences with no filler. The first sentence states the core function; the second explains the key usage pattern. Information is front-loaded and each clause earns its place.

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

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

The description covers the main behavioral loop: read, get offsets, pass them back, optionally wait. It also indirectly signals the response contains next_stdout_offset and next_stderr_offset. Given no output schema, this is sufficient for an agent to invoke and interpret results 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 100%, so baseline is 3. The description adds value by explaining where the offset parameters come from ('previous next_stdout_offset and next_stderr_offset values') and clarifying the effect of wait_ms. This enriches the schema's minimal per-parameter descriptions.

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: 'Read captured stdout and stderr from a managed background process.' This clearly distinguishes it from siblings like process_status, process_wait, and process_write, and makes the tool's role immediately obvious.

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 usage context: how to use offsets for incremental reads and wait_ms for blocking behavior. It doesn't explicitly mention alternatives or when not to use it, but the context is concrete enough that an agent can decide when to invoke it.

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

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

The description adds significant behavioral context beyond the annotations: 'Bounded mutation', no-op with a reason, immediate return with delayed effect, the need to poll runtime_info, and refusal when unsupervised. This fully characterizes the tool's side effects and timing.

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 deliver complete operational guidance with no filler. The first sentence front-loads the most important classification ('Bounded mutation') and the exact trigger condition, followed by return behavior and constraints.

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

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

Given no parameters and no output schema, the description covers all essential context: what the tool does, when it acts, when it does nothing, what the caller experiences, how to observe the outcome, and a safety precondition. 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?

There are zero parameters and the schema is an empty object with 100% coverage, so the description has no parameter burden. It still adds relevant semantic context about the action's bounds and conditions, which is more than sufficient for a parameterless tool.

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 action ('Restarts the worker') and precise triggering condition ('only when it demonstrably serves a stale build'), with concrete detection criteria. It clearly distinguishes this tool from siblings like runtime_info, machine_status, and self_update.

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 says when to invoke the tool (when a stale build is demonstrated), when not to (no-op when fresh), and what to do after (poll runtime_info for the new worker). It also names an exclusion condition ('Refuses when unsupervised').

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

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

Beyond the annotations, the description discloses that this is an unrestricted control environment, explicitly not a sandbox, and only available with a danger flag. It also reveals that state survives across calls via session_id. This materially augments the annotation hints and gives the agent a clear risk picture.

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 purposeful sentences front-load the core purpose, then provide usage syntax, then the safety warning. There is no filler, and each 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 complex arbitrary-code execution tool with no output schema, the description covers the execution environment, persistence semantics, MCP invocation, structured return via result(value), and safety gating. Combined with the high-coverage input schema and annotations, an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context above the schema by documenting how to interact with MCP capabilities from code (await tools.<name> or await call) and by elaborating that variables/imports/helpers persist per session_id.

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: 'Execute model-generated Python in a persistent IPython/Jupyter kernel.' This clearly separates it from shell/process executors among the sibling tools, and the persistence detail adds a distinguishing scope.

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 implies when to use the tool—when persistent Python state and MCP capability access are needed—and gives in-kernel usage patterns. However, it never names alternatives or states when not to use it, so the routing guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with its opening 'Read-only'. It adds useful behavioral context by listing the specific state areas the tool inspects, including the last control restart receipt, going beyond the annotation hints.

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

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

One dense, front-loaded sentence that starts with the most important trait, 'Read-only', followed by a compact colon-separated list of all returned information. Every element carries meaningful information 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?

With zero parameters, strong read-only annotations, and no output schema, the description carries the full burden of explaining what will be returned. It does so by enumerating every visible area of runtime state, making the tool fully usable by an agent without additional lookup.

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 has zero parameters, so the baseline is 4. The description does not need to document parameter semantics, and it does not attempt to add irrelevant parameter guidance.

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 read-only framing and enumerates exactly what the tool exposes: build commit, worker PID, tunnel ownership, contract fingerprint, capability count, and restart receipt. This clearly distinguishes it from sibling tools like system_info or process_status by naming unique control-plane fields.

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

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

The description implies diagnostic use of a control-plane handshake and the listed fields give an agent a strong hint about when it is relevant. However, it does not explicitly state when to prefer this over related siblings such as system_info, machine_status, or environment_info, nor does it provide 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?

The description goes well beyond the annotations by disclosing specific behavioral safeguards: blocks local/private hosts, limits redirects and size, and sends no cookies or credentials. This gives an agent actionable expectations about network safety and auth behavior that annotations 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 tightly packed sentences with no fluff: the first states the core action, the second lists the key constraints. Everything present earns its place and is front-loaded.

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

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

Given the tool's moderate complexity, the annotations, and full schema coverage, the description is largely complete for an agent to understand the operation and safety profile. It does not describe return values or exact overrite behavior, but those are partially covered by the overwrite parameter and are minor gaps for a download tool.

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

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

Schema description coverage is 100%, so the schema already defines url, path, and overwrite. The description adds format context (PNG/JPEG/WebP) but does not materially extend the meaning of the parameters beyond what the schema states. 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 opens with a specific verb and resource—'Download an HTTPS PNG, JPEG, or WebP image to the machine'—making the tool's function unmistakable. It clearly distinguishes this network-download tool from local file tools like read_file or write_file in the sibling list.

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

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

The description provides clear context for when to use the tool: remote HTTPS images, not local or private hosts. It also implies exclusions by stating that credentialed or cookie-dependent URLs will not work. However, it does not explicitly name an alternative tool for those unsupported cases, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral detail beyond annotations: ripgrep fallback to a built-in scanner, support for context lines, per-file cap, and files-only mode. No contradiction with 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 concise sentences with no filler. The primary purpose is front-loaded, followed by relevant implementation behavior and a compact feature list. 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 search tool with 10 params and no output schema, the description adequately conveys return format, implementation variance, and supported modes. It does not cover error/timeout behavior, but schema documents timeout_ms and max_results, so nothing critical is missing 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 every parameter documented in the input schema. The description mentions a few high-level features (context lines, per-file cap, files-only) but adds no new semantic detail beyond what the schema already provides, so the baseline score applies.

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

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

The description states a specific verb and resource ('Search file contents') and defines the structured output (path, line, column, text matches). It is immediately distinguishable from sibling tools like find_files, which searches filenames, and read_file, which reads specific files.

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 provides clear context: search file contents for code-level matches, and the files-only mode is positioned as a 'cheap survey' option. It does not explicitly name alternative tools or state when-not-to-use, but the core use case 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?

The description goes well beyond the annotations by detailing refusal conditions, the exact operation sequence (pull, build, verification, restart), and the post-restart handshake. It also discloses that the call returns before the restart completes and instructs polling runtime_info, which is critical behavioral context.

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

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

Three dense sentences carry all essential information with no filler. The privileged nature and required environment variable are front-loaded, followed by refusal conditions and then the action sequence and return 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 complex, destructive autonomous operation with no output schema, the description is remarkably complete: it covers prerequisites, failure conditions, the mutation sequence, restart behavior, and the expected follow-up action. An agent has enough to decide whether to invoke it and what to expect.

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 has zero parameters and the schema documents 100% coverage. There is no parameter ambiguity to resolve, so the description appropriately adds no parameter-level detail. The baseline for a zero-parameter tool is satisfied.

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 and resource: an autonomous self-update via fast-forward-only pull, build, verification, and supervised restart. It clearly distinguishes this from simple restart or status tools by describing the full update pipeline.

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 usage context: this is a privileged update path that requires MCP_ALLOW_SELF_UPDATE=1 and refuses under specific repository conditions. It does not explicitly name alternative tools or state when not to use it, but the preconditions and refusal conditions effectively define appropriate usage.

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?

Adds useful behavioral context beyond the annotations: the command is awaited synchronously, and long-running work should be delegated to start_process. The destructive/open-world/read-only hints are already covered by annotations, so the description doesn't need to restate them, though it doesn't detail output handling or exit code reporting.

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 concise sentences with no wasted words. The main behavior and workspace scope are front-loaded, and the important alternative is named immediately afterward.

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 tool with 9 parameters and no output schema, the description is adequate but minimal: it defines workspace root and blocking behavior, while return values and output capture are left implicit. Annotations and schema compensate for destructive hints and timeout/exit-code options, but the absence of any return-semantics note leaves 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?

The schema documents 8 of 9 parameters clearly, so description-level parameter explanation is largely unnecessary. The description adds no parameter-specific detail, but with 89% schema coverage the baseline of 3 is appropriate; only the 'shell' parameter lacks a description, and its enum values communicate the choices.

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?

Clearly names the action ('Run a shell command'), the scope ('inside the configured workspace root'), and the blocking behavior ('wait for it to finish'). It also distinguishes itself from the sibling start_process by explicitly recommending that tool for long-running commands.

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 routing guidance: use this tool for short commands that finish normally, and 'Use start_process for anything long-running.' This directly addresses the most likely alternative and gives a clear selection 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true. The description adds that a PID is returned and that read_process_output should be used to poll output, but it does not elaborate on side effects, workspace constraints, or lifecycle cleanup.

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

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

Two short sentences with no filler. The main action and return value are front-loaded, and the polling note is a concise, valuable addition.

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 no output schema, the description usefully specifies that the tool returns a PID and points to read_process_output for consuming output. It is mostly complete, though it could mention process lifecycle aspects or failure modes, but those are reasonably inferable from the annotations and sibling tools.

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 input schema already documents command, env, shell, and workdir with about 75% coverage. The description adds no per-parameter meaning beyond saying the command runs in the background; it correctly stays at the baseline because the schema covers most param semantics.

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

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

The description uses a specific verb and resource: 'Start a background process inside the configured workspace' and states the key result, 'return its PID.' It is distinguishable from siblings like shell_command through the explicit 'background process' framing, though it does not name alternatives directly.

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 a useful follow-up instruction ('Poll it with read_process_output') and the phrase 'background process' implies use for long-running work. However, it does not explicitly explain when to choose this over shell_command, process_status, or stop_process, or mention any 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?

Annotations already declare destructiveHint=true. The description adds meaningful behavioral detail beyond the annotation by stating that the operation stops both the process and its child tree, and that it applies only to managed background processes. No contradiction with 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?

The description is a single front-loaded sentence with no filler. Every word contributes meaning: 'stop', 'managed background process', 'child tree', and 'by PID' all carry useful information.

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

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

For a fairly simple destructive operation, the combination of schema, annotations, and description covers the essential invocation details. The description could mention return behavior or stale-process handling, but those are not critical for correctly identifying and invoking the tool.

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

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

Schema description coverage is 100%, with both pid and process_id clearly documented in the schema itself. The description adds only the general 'by PID' mechanism and 'managed background process' context, which does not significantly expand on the structured parameter definitions.