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 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 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 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?

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, 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 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 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 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?

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?

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 establish read-only and non-destructive behavior. The description adds meaningful extra context by stating that no shell is invoked, which is a useful behavioral guarantee. It does not discuss response format, but for a no-parameter read-only info tool this is a minor omission.

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 that front-loads the action and lists all relevant data categories without extraneous wording. Every part of the 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 tool with no parameters and no input complexity, the description fully covers what the tool does, what data it returns conceptually, and a key safety/behavioral characteristic. Nothing essential 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?

The tool has zero parameters and schema coverage is effectively 100%, so there is nothing for the description to add about parameter meaning. The baseline of 4 for a zero-parameter tool 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 ('Read') and enumerates exactly what is retrieved: operating-system, CPU, memory, uptime, Node.js, and host identity information. It also distinguishes itself from shell-based tools by explicitly stating it works without invoking a shell, which separates it from siblings like 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 context: use this tool to obtain system-level identity and resource information without shell execution. It does not explicitly name alternatives like environment_info or machine_status, but the phrase 'without invoking a shell' implies a safe, read-only alternative to shell-based 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 destructiveHint=true, and the description adds valuable beyond that: it warns that line numbers shift after every edit and that the target must be an existing UTF-8 text file. This gives the agent important behavioral expectations without contradicting the annotations.

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

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

Two sentences with no filler: the first states the core action and constraints, the second delivers the critical caveat about line shifts. 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 destructive line-range mutation, the description covers the operation, file constraints, and the freshness caveat. The schema covers parameter semantics and the optional SHA check. It does not explain edge cases like start_line > end_line or return values, but these are not essential given the schema and 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 100%, so the schema already documents all parameters thoroughly, including optional expected_sha256. The description adds the line-shift caveat, which is relevant to start_line/end_line usage, but does not provide additional per-parameter detail beyond what the schema offers.

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: replacing an inclusive, 1-based line range in an existing UTF-8 text file. This clearly distinguishes it from sibling tools like write_file, which writes whole files, and apply_patch, which applies patches.

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 clear that the file must already exist and provides an important sequencing rule: read the file again between edits because line numbers shift. It does not explicitly mention alternatives or when not to use this tool, but the context is clear enough for an agent to decide when line-range editing 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 destructiveHint=true, but the description adds meaningful behavior beyond that: it specifies UTF-8 encoding, create-or-replace semantics, and the condition under which replacement occurs. This is useful context not present in the annotations, though it does not elaborate on failure modes or the optimistic concurrency check beyond what the schema provides.

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 written sentences with no filler. The primary purpose is stated first, the conditional behavior second, and the sibling guidance last. Every sentence earns its place.

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

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

The description covers the core semantics and guides tool selection, while annotations cover the safety profile and the schema covers all parameters. Minor gaps remain, such as failure behavior and the concurrency guarantee of expected_sha256, but these are adequately represented in structured fields and are not critical for an agent to invoke 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%, and the schema already documents each parameter including the default of 'overwrite' and the purpose of 'expected_sha256'. The description adds no significant parameter-level detail beyond echoing 'overwrite' and 'content', 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?

Description uses a specific verb ('Create') with a concrete resource ('UTF-8 text file') and clearly states the replace behavior conditional on 'overwrite'. It also distinguishes itself from siblings by directing changes to existing files toward edit_file or update_file. An agent can unambiguously understand this tool's role.

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

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

The description explicitly says 'Prefer edit_file or update_file for changes to an existing file', giving clear guidance on when not to use this tool and naming the alternatives. This directly helps an agent choose the right sibling tool without additional inference.

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