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

With no annotations, the description does real work: it caps requests at 200 and concurrency at 20, discloses what is reported (status counts, errors, latency percentiles), and flags the ownership/authorization caveat. It stops short of saying whether requests are fired all at once, whether it honors redirects, or how failures are counted.

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: the capability and its hard limits come first, the safety constraint last. No filler and nothing restates 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?

An output schema exists, so return values need not be described, and the description still previews them plus the request/concurrency ceilings. It is nearly complete for a five-parameter tool, with only the unmentioned `method` and `timeout` semantics keeping it from a 5.

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

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

Schema coverage is 0%, so the description must carry the burden, and it only annotates two of five parameters: `requests` (max 200) and `concurrency` (max 20). `method`, `timeout` and the target `url` shape/format get no semantic treatment, leaving half the surface undocumented.

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

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

States a specific verb and resource: send N requests with C workers and report status counts, errors and latency percentiles. That outcome profile ('latency percentiles', 'status counts') makes it unmistakably a load probe rather than a single-request sibling like http_request or check_tcp_port.

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 only usage guidance is the caution 'Use only against systems you own,' which is a safety constraint, not a when-to-use rule. Nothing tells the agent when to pick this over http_request or run_command, so the selection logic is only implied by the word 'load probe.'

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

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

With no annotations, the description carries the burden; it does disclose the output encoding (JSON lines) and the auditing-enabled precondition, which are useful. However, it never says what happens when auditing is disabled (error vs empty result) or whether the read is bounded, leaving real behavioral gaps.

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

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

A single front-loaded sentence with no waste; the format and precondition are packed in efficiently. Brevity is close to the limit of usefulness rather than verbose.

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

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

An output schema exists, so return structure needn't be explained, and the description covers the basic purpose and precondition. But for a log-reading tool it omits the 'lines' parameter and the disabled-auditing behavior, so an agent still has open questions.

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

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

Schema coverage is 0% and the single 'lines' parameter (default 20) is never mentioned. Its name is fairly intuitive, but the description adds no meaning about count semantics, maximums, or ordering beyond the vague 'most recent'.

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

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

States a specific verb and resource ('Return the most recent audit log entries') and adds the output format ('JSON lines'). This distinguishes it reasonably from neighbors like read_event_logs or git_log, though it never explicitly names a 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?

There is no when-to-use guidance and no named alternative. The clause 'if auditing is enabled' is a precondition, not usage guidance, and the agent is left to infer when to reach for audit_tail over read_event_logs.

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

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

No annotations are provided, so the description carries the burden: it does convey this is a non-destructive probe that reports connect time. However, failure semantics are undisclosed — whether a refused/timed-out connection raises an error or returns a negative result — which materially changes how an agent should invoke and interpret it. Return shape is covered by the output schema, so the penalty is limited.

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

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

A single front-loaded sentence with zero filler; the action, the target, and the notable output all land in one clause. Nothing needs trimming — the gaps are omissions, not verbosity.

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

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

The tool is simple, the output schema documents the return value, and the core action is stated. Still missing for correct invocation: timeout units/scope and behavior on connection failure — the two things an agent most needs beyond the schema for a network probe with no 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 only re-uses 'host:port' from the schema and says nothing about the third parameter, timeout — its units (schema default of 3 is unit-less), whether it bounds only the connect phase, and what happens on expiry. Only the two obviously-named params are indirectly covered.

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?

Specific verb+resource: 'Test whether a TCP connection to host:port succeeds' is unambiguous and distinct from listing tools (list_ports) or higher-level probes (http_request, api_load_test). It also names the primary output, connect time. It stops short of explicitly contrasting with the nearest siblings, so 4 rather than 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?

No when-to-use or when-not guidance. The agent must infer that this is the connectivity-probe option versus http_request, dns_lookup, or list_ports. Nothing states prerequisites (firewall, host reachable) or what alternative to pick when the host is unresponsive.

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

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

No annotations exist, so the description carries the full burden; it does disclose the read-only nature and Windows-only requirement, which is real value. However it says nothing about required privileges, remote-target behavior, whether the default limit of 50 truncates results, or what happens on a namespace miss.

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 compact sentences, front-loaded with the operation and constrained by platform before the parameter detail. Slight waste in the 'e.g.' class enumeration, but it earns its place as discovery aid for an agent that doesn't know WMI class names.

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

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

An output schema exists so return shape needn't be described, and the read-only/Windows facts are covered. Still, for a 5-parameter tool with 0% schema coverage, the absence of any guidance on namespace selection, property projection, or limit truncation leaves an agent guessing on most of the surface.

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

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

Schema description coverage is 0%, so the description must compensate, and it only half does: it clarifies `filter` as a WQL WHERE clause with a concrete example and implies `class_name` via the example class list. The `namespace`, `properties`, and `limit` parameters receive no explanation at all, despite `limit` having a truncation-relevant default of 50.

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

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

Names a specific verb and resource ('Query CIM/WMI classes via Get-CimInstance') plus the platform constraint, and the enumerated example classes make the scope concrete. This is clearly distinguishable from siblings like system_info, list_processes or list_services.

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 'Windows only' qualifier and the example classes imply when this tool applies, but there is no explicit 'use X instead' routing to overlapping siblings such as system_info, list_processes or list_services. Usage is inferred rather than stated.

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

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

With no annotations, the description carries the behavioral burden and does disclose important traits such as psd1 requiring pwsh in restricted language mode and XML using @attr/#text conventions. However, it does not describe overwrite behavior when output_path is used, error handling, or other operational limits.

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

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

The description is compact and front-loaded with the core conversion purpose and supported formats. Each sentence adds operational detail without 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 description is largely complete for a conversion tool, especially since an output schema exists and return formatting need not be explained. It covers input modes, format inference, output writing, psd1 requirements, and XML conventions, but omits edge-case behavior such as overwrites.

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 meaningfully explains path/text input, from_format inference from extension, output_path writing behavior, and to_format through the listed target formats, though it does not explicitly call out to_format as required.

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, 'Convert', and names the supported formats json, yaml, toml, csv, xml, and psd1. It clearly identifies the resource and operation, though it does not explicitly differentiate itself from siblings such as pandoc_convert.

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 explains that either path or text may be provided, that from_format is inferred from the file extension when omitted, and that output_path controls whether the result is written or returned. It does not explicitly state when to choose this over alternatives like pandoc_convert or query_data.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions parent directory creation, which is useful, but omits critical mutation behavior such as overwrite semantics, error conditions, permission requirements, and whether existing files are preserved or replaced.

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 immediately states the action, the resource, and the parent-directory 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?

Although an output schema exists and need not be explained, this is a mutation tool with no annotations and zero schema description coverage. The description is too sparse for a three-parameter file-creation operation because it omits overwrite behavior and error handling that an agent needs to invoke it safely.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It implies path and content through 'file' and 'given content', but never mentions the overwrite parameter or its default behavior, leaving a required parameter completely undocumented.

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: 'Create a file'. It also clarifies that parent directories are created and content is provided. However, it does not distinguish this tool from the sibling edit_file, which also creates or modifies 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?

There is no guidance on when to use create_file versus edit_file or other file tools. It also does not state when overwrite should be used or what happens if the file already exists, leaving the agent to infer usage from the name alone.

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

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

With no annotations, the description carries full behavioral burden. It usefully discloses recursive directory deletion, but omits critical behavior for a destructive operation: whether deletion is permanent, whether permissions or confirmation are required, and how errors are handled.

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 is concise and structurally appropriate, even though it omits necessary safety details elsewhere.

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 recursive delete tool with no annotations and 0% schema description coverage, the definition is under-specified. It mentions recursion but lacks safety, permanence, and path semantics, leaving important gaps 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 0%, and the only parameter is undocumented in the schema. The description adds only that path may refer to a file or directory; it does not clarify path format, relative vs. absolute paths, or constraints.

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 has a specific verb and resource: delete a file or directory, and it adds the important scope detail that directory deletion is recursive. It distinguishes the tool clearly from read/create/edit siblings, though it does not explicitly contrast it with other deletion mechanisms or state permanence.

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

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

There is no guidance on when to use this tool versus alternatives, prerequisites, or cautionary conditions. It does not warn when not to use it or mention confirmation/irreversibility expectations.

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

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

No annotations are provided, so the description carries the burden, and 'using the system resolver' is a genuine behavioral disclosure — it tells the agent results reflect local resolver config (hosts file, configured DNS), not authoritative DNS. However, it says nothing about failure behavior (NXDOMAIN vs error), timeouts, or whether both A and AAAA records are returned.

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

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

One short sentence, front-loaded with the verb and free of filler. It is arguably slightly under-specified rather than bloated, which is the right kind of brevity failure.

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

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

An output schema exists, so return values need not be described. But for a network-dependent tool with no annotations and an undocumented parameter, the description should at least flag error behavior and record-type scope; neither 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?

The single 'host' parameter has 0% schema description coverage, so the description must compensate; calling it a 'hostname' clarifies that a name rather than an IP literal is expected. It still omits format expectations (FQDN vs short name, trailing dot, scheme rejection), leaving the one parameter only partially specified.

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?

Specific verb ('Resolve') plus resource ('hostname') and the outcome ('its addresses'), so an agent knows exactly what the call produces. It does not explicitly distinguish itself from nearby network siblings like check_tcp_port or http_request, which is the only thing keeping it from 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?

There is no statement of when to use this versus alternatives such as web_fetch or http_request, and no mention of prerequisites like whether the hostname must be fully qualified or whether the host must be reachable. The usage is only implied by the verb.

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

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

With no annotations, the description carries the full burden and does disclose the two traits that matter most for a mutation tool: the exact-single-match failure mode and that dry_run returns a unified diff without writing. It omits whether the file must already exist, atomicity of the write, and encoding handling.

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, zero filler, with the core operation first, the failure condition second, and the safe-preview option last. Every sentence carries distinct 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?

An output schema exists so return values need not be described, and the description covers the failure mode plus the dry-run preview — the two things an agent most needs before mutating a file. Missing only secondary details like whether the target file must exist and whether edits are atomic.

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

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

Schema description coverage is 0%, so the description must compensate; it explains old_string/new_string by naming them, defines replace_all's effect via the uniqueness clause, and spells out dry_run's return behavior. Only 'path' is left unstated (though implied by 'in a file'), and matching semantics such as whitespace/escaping sensitivity are not addressed.

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

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

States a specific verb+resource: replace old_string with new_string in a file. That distinguishes it in spirit from edit_file_multi (multi-edit) and replace_lines (line-based), but no sibling is named explicitly, so the agent must infer the boundary itself.

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

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

Gives an actionable precondition ('fails unless it matches exactly once') and the escape hatch ('replace_all is true'), which is effectively guidance on when this call will succeed. It never says when to prefer replace_lines or edit_file_multi instead, so the alternative-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?

With no annotations at all, the description carries the full burden, and it delivers the two behaviors that matter most for a mutation tool: sequential ordering and all-or-nothing failure semantics ("if any fails nothing is written"). It omits whether the file must already exist and says nothing about the dry_run escape hatch, which is a notable gap for a write operation.

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

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

Two sentences plus an inline payload sketch, no filler. The atomicity guarantee, which is the decisive fact for an agent choosing this tool, is front-loaded in sentence one.

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

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

An output schema exists, so return values need not be described, and atomicity is covered. But for a mutation tool with zero annotations, leaving dry_run unexplained and not stating whether path must point at an existing file leaves real gaps an agent must guess at.

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. It documents the edits payload well, spelling out old_string/new_string and the optional replace_all flag that the bare additionalProperties schema leaves undefined. However, path and especially dry_run (default false, a meaningful control surface) get no explanation anywhere.

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?

"Apply several edits atomically" gives a specific verb (apply edits), a quantified scope (several), and a defining property (atomic) that separates it from the single-edit siblings edit_file and replace_lines. It stops short of naming those siblings explicitly, so the distinction is inferable 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 word "atomically" and the plural "edits" imply the use case (batch changes that must all succeed or none), but the description never states when to prefer this over edit_file or replace_lines, nor what preconditions apply to path. Usage is implied, not guided.

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

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

With no annotations, the description carries the burden, and it does disclose one important behavior: secret-looking values are redacted, which sets expectations about output completeness. It says nothing about read-only semantics, permissions required, or whether redaction is logged, which is thin for a zero-annotation 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?

Two compact sentences, scope first, caveat second — nothing wasted and no filler. Front-loaded with the resource identity before the behavioral warning.

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

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

An output schema exists so return values need not be explained, and the redaction caveat is a useful addition. However, the undocumented name_contains parameter leaves the definition incomplete for a tool that otherwise is simple enough to fully cover in one more clause.

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 never mentions the name_contains filter at all, so an agent reading only the description would not know filtering by name is possible. This is the clearest gap given only one parameter exists and it goes undocumented in prose.

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 the specific resource (environment variables) and scopes it to the server process, so an agent knows it is not reading a remote host's env. It lacks an explicit verb and does not distinguish itself from nearby system-inspection siblings such as system_info or workspace_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?

There is no statement of when to reach for this tool versus alternatives like system_info, nor any prerequisites or exclusions. An agent must infer usage purely from the resource name.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the safety-relevant fact that check_only=True is report-only, but it never states what happens when check_only=False — presumably in-place file modification — nor whether it touches one file or a whole tree, which for an un-annotated mutating tool is a notable gap.

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

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

A single dense sentence with the mutating verb front-loaded and no filler. It is arguably too terse rather than verbose, which is a completeness problem, not a conciseness one.

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

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

An output schema exists so return values need no explanation, but the description leaves critical gaps for a tool that can rewrite files: no in-place vs preview default, no path scope semantics, and no cwd meaning. For a three-parameter mutation tool with zero annotation and zero schema-description coverage, this is under-specified.

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% across three parameters, and the description only glosses `check_only`. `path` (default '.') is entirely undefined — file or directory, recursive or not — and `cwd` is never mentioned, so the description fails to compensate for the empty schema documentation.

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 (format), a specific resource (Python code), and the engine (ruff), which cleanly separates it from the sibling `lint` tool. It does not explicitly name that sibling or contrast itself with it, so it stops short of a 5.

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

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

The clause 'check_only=True only reports' implies a preview-vs-apply usage mode, which is genuinely useful context. However, it never says when to pick this over `lint` (a very close sibling) or that the default is the non-mutating mode, so usage is only implied rather than guided.

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

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

With no annotations, the description carries the full burden. 'Return' implies a non-mutating lookup, and the error-recovery framing is useful context, but the description never explicitly confirms the call is side-effect free, nor does it state behavior for an unrecognized topic.

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 purpose, followed by the actionable trigger. The parenthetical topic list is long but earns its place by supplying the missing enum values.

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

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

For a single-optional-parameter lookup tool with an output schema covering return values, the description supplies purpose, valid inputs, and call conditions. The only residual gap is unknown-topic behavior, which is minor given the tool's simplicity.

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

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

Schema coverage is 0% and the single 'topic' parameter has no description or enum, so the description must compensate — and it does, enumerating all nine valid topic groups plus 'index' as the default. That is exactly the semantic detail the schema lacks.

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

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

States a specific verb and resource ('Return usage docs and examples for a tool group') and enumerates the exact topic domains, so an agent knows precisely what it gets back. No sibling tool in the list produces documentation, so the function is unambiguously differentiated.

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

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

'Call this after a tool error' gives an explicit trigger condition and makes the tool's role as an error-recovery aid clear. It stops short of stating when not to call it (e.g. during normal operation) or what to do if the topic is unknown.

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

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

No annotations are provided, so the description carries the full burden. It never states that staging mutates the git index, what happens when a path is missing, or that staging the repo root can sweep in unintended files — significant gaps for a mutation tool with zero 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?

It is a single front-loaded phrase with no padding, which is structurally clean, but it is under-specified rather than efficient — the brevity comes at the cost of any 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?

An output schema exists so return values needn't be described, but with no annotations and no parameter documentation, a two-parameter git mutation tool needs more than two words. Nothing an agent needs to invoke it safely 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 0%: only titles ('repo', 'paths') exist. The description's word 'files' loosely hints at the required 'paths' array but says nothing about glob/pattern support, multiple paths, or what the default repo value '.' means.

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 phrase names a specific git verb and resource ('Stage files'), which is precise within git vocabulary and cannot be confused with siblings like git_commit or git_diff. It offers no explicit differentiation from those siblings, but the action itself is unambiguous.

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

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

There is no guidance on when to stage versus when to commit, no mention that staging must precede git_commit, and no note about which paths to include. The agent must infer the whole workflow context from git conventions alone.

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

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

No annotations exist, so the description carries the safety burden and does disclose 'read-only', which is the key behavioral fact for a git inspection tool. However it says nothing about what happens with an invalid path, an uncommitted working tree, or repository/permission prerequisites.

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, front-loaded with the core action and the safety trait, ending with the only optional behavior an agent needs at call time. Nothing 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?

An output schema exists, so return values need no explanation, and the read-only trait plus line-range option cover the essentials. But with four parameters at 0% schema coverage, the description leaves the 'repo' parameter and line-range semantics unexplained, which is a real gap 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 0%, so the description must compensate and largely does not: it implies a file path and a start/end line range but never explains the 'repo' parameter (default '.') or clarifies line-range numbering, inclusivity, or whether start/end can be supplied independently.

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

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

States a specific verb and resource ('Show who last changed each line of a file') that names the exact git blame semantic and distinguishes it from git_log (history) and git_diff (changes), with no overlap in interpretation.

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

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

Usage is implied rather than stated: an agent can infer this is for line-level attribution, and 'optionally limit to a line range' hints at a narrowing use case, but there is no explicit when-to-use vs git_log/git_diff guidance or prerequisite 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?

With no annotations, the description carries the burden and does add one real behavioral guarantee: 'Never overwrites an existing branch'. It does not say what happens on a name collision (error vs no-op), what start_point defaults to, or whether creating with switch modifies the working tree.

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 zero waste; the action is front-loaded and the safety guarantee follows immediately. Every clause carries distinct 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?

An output schema exists, so return values need no explanation, and the non-overwrite guarantee covers the main safety concern. The remaining gap is that two of four parameters and the collision/error behavior stay undocumented.

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

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

Schema description coverage is 0%, so the description must compensate and only partially does: it mentions the branch name implicitly and covers 'switch' ('optionally switch to it'). The 'repo' and 'start_point' parameters are entirely undocumented in both 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?

States a specific verb+resource ('Create a new branch') and adds useful scope ('optionally switch to it'). It doesn't name the sibling git_switch that overlaps with the switch behavior, so differentiation from siblings is implied rather than explicit.

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

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

Usage is only implied: the description says the tool creates a branch and may also switch, but never says when to use git_branch_create with switch=true versus calling git_switch separately. No prerequisites (clean working tree? existing repo?) are given.

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

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

With no annotations, the description carries the full burden and does reasonable work: it declares read-only semantics explicitly and discloses the shape of the result (last commit + upstream), plus the implicit default of local-only scope implied by 'all_branches includes remotes'. It stops short of stating ordering, pagination, or behavior on a non-repo path.

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, zero filler, and the core capability plus the read-only guarantee are front-loaded before the parameter note. Nothing could be removed without losing 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 two-optional-parameter read tool with an output schema (so return format needn't be described), the definition covers purpose, safety, and scope adequately. The remaining gap is the unexplained 'repo' parameter and default path semantics, which is minor but real.

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 supply meaning. It clarifies all_branches ('includes remotes') and implicitly confirms that the default excludes remotes, but says nothing about the 'repo' parameter beyond its existence, leaving one of two parameters undocumented anywhere.

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

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

The description gives a specific verb and resource ('List branches') and states what each entry carries (last commit and upstream), which separates it from git_branch_create and git_switch. It does not explicitly name a sibling it competes with, but the verb/resource pairing makes the distinction 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?

There is no explicit statement of when to choose this over git_status, git_log, or git_remote_info; the only conditional text ('all_branches includes remotes') is parameter behavior, not usage guidance. An agent must infer that this is the inspection tool for branch inventory.

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

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

No annotations are provided, so the description carries full behavioral burden. It implies a mutation ('commit'), but does not disclose whether the commit is reversible, what permissions are needed, what happens on failure, or what the commit includes beyond staged changes.

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

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

The description is a single short sentence with no waste, but its extreme brevity leaves critical details unstated. It is efficient rather than well-structured for a mutation tool.

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

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

For a mutation tool with no annotations, 0% schema description coverage, and only a two-word description, much is missing. The presence of an output schema removes the need to describe return values, but prerequisites, parameter meaning, and behavioral effects remain inadequately covered.

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 mentions neither the required 'message' parameter nor the optional 'repo' parameter. An agent gets no semantic guidance from the description about what these parameters mean or how to supply them.

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

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

The description states a specific verb and resource: 'Commit staged changes.' It distinguishes the operation from staging tools like git_add by specifying that only already-staged changes are committed. It does not explicitly name sibling alternatives, but the purpose is clear enough for selection.

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

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

The description implies that the tool is used after staging changes, but provides no explicit when-to-use guidance, no prerequisites such as needing a repository or a prior git_add call, and no alternatives for related workflows.

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

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

No annotations are provided, so the description carries the burden. "Show" implies a read-only operation, and the output schema covers the return shape, but the description does not state permissions, whether untracked files appear, or any other behavioral trait.

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

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

One short sentence, front-loaded with the core action and no wasted words. It is appropriately sized for a simple git tool.

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

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

For a simple read-only tool with an output schema, the essentials are covered, but the missing explanation of the 'repo' parameter and the absence of any comparative guidance against git_diff_stat leave it only minimally complete.

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

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

Schema description coverage is 0%, so the description should compensate. It does explain 'staged' and 'path' at a high level, but the 'repo' parameter and its default '.' are completely unaddressed, leaving a meaningful gap.

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

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

States a specific verb and resource ('Show git diff') plus the two optional scoping modes (staged/path). It is clear what the tool does, though it does not explicitly distinguish itself from the nearby git_diff_stat 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?

Only implies usage by listing the optional flags. It never says when to prefer this over git_diff_stat, git_show, or git_status, nor does it give preconditions or 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?

No annotations are provided, so the description carries the full burden. It does disclose read-only behavior, which is useful, but says nothing about what staged does, what repo defaults to, or how the per-file summary is shaped.

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, front-loaded sentences with no padding. The phrasing 'base compares with a revision' is slightly awkward but efficient overall.

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

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

An output schema exists, so return values need not be explained. However, with no annotations and 0% schema coverage, leaving 'repo' and 'staged' entirely unexplained is a significant gap for a tool with three parameters.

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 only clarifies 'base' as a comparison revision; 'repo' and 'staged' remain completely undocumented in both 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?

States a specific verb and resource ('Summarise changes per file') and scopes it with 'compact for large diffs', which distinguishes it from the fuller git_diff sibling. It stops short of naming that sibling explicitly, so an agent must infer the trade-off.

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?

'compact for large diffs' implies when to prefer this over git_diff, but the guidance is indirect. There are no explicit exclusions or conditions for choosing between git_diff_stat, git_diff, and git_show.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that the operation is non-destructive and leaves existing repositories intact, which is valuable behavioral context. However, it does not mention permissions, error behavior, or what happens if a repository already exists beyond 'left intact'.

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

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

A single short sentence with zero waste. The non-destructive caveat is front-loaded alongside the core action, and every word earns its place.

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

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

An output schema exists, so return values need not be explained. The tool is simple, but with no annotations and no parameter descriptions in the schema, the description omits essential information about the two inputs. It is minimally adequate for a very simple tool but leaves 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 must compensate for the two undocumented parameters. It says nothing about the 'repo' path or 'initial_branch' argument, leaving the agent to infer meaning from parameter names and defaults 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 states a specific verb and resource: 'Initialise a new git repository'. It is immediately clear what the tool does and there is no ambiguity with sibling tools like git_status 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?

Usage is implied by the tool's purpose, but there is no explicit guidance on when to use it versus alternatives, no prerequisites, and no exclusions. The non-destructive note implicitly reassures but does not provide selection guidance.

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

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

No annotations are provided, so the description carries the full disclosure burden, and it says almost nothing: no read-only confirmation, no ordering (newest-first?), no default of 10 commits, no behavior when the repo path is invalid or is not a git repository. 'Recent' is the only behavioral hint.

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

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

A single short sentence with zero waste, but the brevity comes from under-specification rather than discipline. There is nothing to front-load because there is essentially one clause.

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

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

An output schema exists, so return values need not be explained, but with no annotations and 0% schema coverage on two parameters, the description leaves the agent guessing about scope, defaults, and safety. For a tool with parameters and no structured documentation, this is inadequate.

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 neither parameter is mentioned: 'repo' (defaults to '.') and 'max_count' (defaults to 10) are completely undocumented in both schema and description. 'Recent' loosely gestures at a limited window but gives no default or range 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?

States a verb ('Show') and resource ('commits') with a recency qualifier, so the basic intent is legible. However, it does not distinguish this from siblings like git_show (single commit detail) or git_diff, and never mentions that the log is scoped to a repo. Purpose is vague rather than specific.

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

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

There is no statement of when to use this versus git_show, git_blame, or git_diff, and no prerequisites or exclusions. The agent must infer usage purely from the tool name.

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

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

With no annotations, the description carries the full burden, and it does disclose the key limitations: no force push, no ref deletion, and the tags-mode switch. However, it says nothing about network/credential requirements, non-fast-forward rejection, or that the operation mutates a remote (an irreversible side effect), which is exactly the context an agent needs before calling a push.

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 primary action and default, then constraints, then the tags special case. No filler and no repetition of the title.

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 5-parameter mutation tool with zero annotation coverage and no schema descriptions, the description is too thin: it omits remote-selection semantics, upstream tracking behavior, and failure conditions. An output schema exists, so return values need not be explained, but the pre-call and side-effect picture is incomplete.

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% across 5 parameters, so the description must compensate and does so only partially: it explains 'tags' and the default for 'branch' (via 'default: current'). Nothing addresses 'repo', 'remote', or 'set_upstream', leaving three parameters with no semantic guidance anywhere.

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

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

States a specific verb+resource ('Push a branch ... to a remote') and specifies the default branch behavior, which an agent can act on directly. No sibling performs pushes, so differentiation is implicit rather than stated; the description also adds scope limits (no force push, no ref deletion) that sharpen the picture.

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

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

It gives one conditional routing rule ('tags=true pushes tags instead of a branch') and a negative constraint (force pushes and ref deletion unsupported), but never says when to prefer this over workflows it depends on (git_commit, git_add, git_branch_create) or what prerequisite state is required. Usage is implied rather than spelled out.

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

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

With no annotations, the description carries the full burden and does meaningful work: it declares the operation read-only and, more valuably, discloses that credentials embedded in remote URLs are masked in the output. It stops short of covering failure behavior (non-git path, missing repo) which would have pushed it to a 5.

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

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

One sentence, front-loaded with the resource and action, with the safety and masking notes appended compactly. Nothing is redundant or padding.

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

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

For a one-parameter read tool with an output schema (so return values need no explanation), the description covers purpose, safety profile, and output sanitization. The remaining gap is the unspecified `repo` path semantics, which is minor but real.

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

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

The single `repo` parameter has 0% schema description coverage, so the description must compensate and it does not mention the parameter at all. An agent gets no clarification on whether `repo` is a path relative to cwd, a worktree root, or what the default '.' resolves against.

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

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

States a specific verb and resource ('List configured remotes and their URLs') with an explicit scope qualifier ('read-only'). No sibling in the provided list covers git remotes, so an agent can select it unambiguously 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 '(read-only)' tag implies this is a safe inspection call, but there is no explicit guidance on when to reach for it versus inspection siblings like git_status, git_branch_list, or git_log, and no prerequisites such as 'repo must be a git working tree' are stated.

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

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

No annotations are provided, so the description carries the full behavioral burden; it does disclose the read-only nature and the two output modes (full diff vs. stat summary), which is real value. However it says nothing about behavior on a bad rev, output size for large commits, or how output differs when path is set, leaving gaps for a tool with zero annotation coverage.

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

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

Two short sentences, zero filler, and the core purpose is front-loaded before the mode hint. Nothing redundant is present.

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

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

An output schema exists, so return-value explanation is not required, and the read-only plus stat_only notes cover the essentials. Still, a 4-parameter tool with 0% schema coverage leaves rev, path, and repo semantics unexplained, which is a meaningful gap 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 0% across 4 parameters, and the description only explains stat_only; 'commit' weakly implies rev but path and repo are never mentioned. A path-scoped show behaves very differently from a full show, and that distinction is absent from both 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?

Specific verb+resource: 'Show a commit's message and diff' tells the agent exactly what is returned, and '(read-only)' flags the operation class. It does not distinguish itself from close siblings like git_diff or git_log, leaving the agent to infer that git_show is per-commit inspection rather than range comparison or history listing.

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

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

Usage is only implied: 'stat_only=true gives only the file summary' hints at a lightweight inspection mode, but there is no statement of when to prefer this over git_diff or git_log. No prerequisites or exclusions are given.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the key trait that the operation is read-only, but says nothing about permissions, scope of the listing (current repo vs all), or behavior of the default repo.

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 words plus a parenthetical, front-loaded and waste-free. It is arguably too terse to be maximally useful, but every element 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 tool is simple and an output schema exists, so return values need not be explained. However, with no annotations and an undocumented repo parameter, the definition is only minimally complete 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 0% and the description never mentions the single 'repo' parameter, so an agent gets no meaning beyond the schema's type and default of '.'. The description fails to compensate for the undocumented parameter.

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

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

States a specific verb and resource ('List stashes') and adds the read-only qualifier, which distinguishes it from mutating git siblings like git_add or git_commit. It doesn't explicitly contrast with nearby read tools such as git_status or git_log, but the resource is unambiguous.

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

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

There is no guidance on when to use this versus git_status, git_log, or git_show, nor any mention of prerequisites or scope. The only implied usage is the literal 'list stashes', leaving the agent to infer everything else.

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

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

No annotations are provided, so the description carries the full disclosure burden and supplies almost none: it doesn't say the operation is read-only, doesn't describe the 'short' output format (porcelain vs. --short), and doesn't note behavior on non-repo paths or dirty/untracked states.

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 zero filler. It is efficient, though the terseness is a symptom of under-specification rather than disciplined 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?

An output schema exists, so return values needn't be spelled out, but with no annotations and an undocumented parameter the description leaves the mutability profile and the 'short' format undefined. For a git inspection tool this is below what an agent needs to invoke it 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?

Schema coverage is 0% and the single parameter 'repo' is documented nowhere. The description never mentions it, its default of '.', or whether it accepts a path or a remote name, leaving the caller to guess.

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

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

States a specific verb and resource (show git status) and 'short' signals the output mode, which distinguishes it from status-adjacent siblings like git_diff and git_log. No explicit sibling differentiation, but the resource is unambiguous.

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

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

There is no guidance about when to call this versus alternatives such as git_diff, git_log, or git_show, and no mention of prerequisites or working-directory assumptions. An agent must infer all of that from the tool name alone.

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

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

With no annotations, the description must carry the burden, and it does disclose one real behavioral trait: git refuses when local changes would be overwritten. It never states that HEAD/working directory is mutated, what happens to uncommitted work, or the success/failure response shape.

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 the action front-loaded and the safety caveat second. Nothing wasted, nothing buried.

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

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

An output schema exists so return values needn't be explained, and purpose plus one safety rule are covered. But for a state-mutating git operation with no annotations and an undocumented 'repo' parameter, the definition is only minimally 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 coverage is 0%, so the description should compensate. It only weakly implies that 'name' is a branch name and gives no meaning at all for the 'repo' parameter (default '.'), leaving half the parameters undocumented everywhere.

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 (switch) and resource (existing branch). The word 'existing' implicitly distinguishes it from git_branch_create, but the sibling is never named explicitly.

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

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

Usage is implied by 'switch to an existing branch', and the overwrite-refusal gives a constraint. There is no explicit routing such as 'use git_branch_create to make a new branch first', leaving the agent to infer the 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that tags are annotated when a message is given and that existing tags are never moved or replaced, but it omits error behavior when a tag already exists, permission requirements, and other operational details.

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 compact sentences with no wasted words, and the key behavioral constraint is front-loaded alongside the creation action.

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

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

An output schema exists, so return values need not be explained. However, for a four-parameter tool with zero schema descriptions and no annotations, the description is thin on parameter meaning and failure behavior, though it does cover the most distinctive tag semantics.

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 only clarifies the semantics of 'message' (annotated tag), leaving 'name', 'repo', and 'target' undocumented beyond their bare titles and defaults.

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: creating a tag, with the annotated/lightweight distinction tied to the message parameter. It clearly differs from siblings like git_branch_create by resource type, though it does not explicitly name 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?

It implies usage by explaining that supplying a message creates an annotated tag, but it does not say when to choose this tool over alternatives or what prerequisites exist. The 'never moves or replaces' line is a constraint rather than usage guidance.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the gitignore-skipping default, that patterns resolve relative to path, and that results are paged via offset. It omits the default result cap and any ordering/symlink behavior, keeping it below a 5.

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

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

Three compact sentences with the core purpose first, then behavioral caveats, then paging. No filler, no repetition of schema structure.

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

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

An output schema exists so return values need not be described, and the critical calling semantics (pattern syntax, base path, gitignore default, paging) are present. The undocumented max_results cap is the one thing an agent might want before calling.

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

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

Schema description coverage is 0%, so the description must compensate, and it covers four of five parameters: pattern, path, respect_gitignore, and offset. Only max_results goes unexplained, which is a minor gap against a strong compensation effort.

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

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

States a specific verb and resource ('Find files by glob pattern') and gives a concrete example pattern plus the resolution base ('relative to path'). It does not explicitly distinguish itself from siblings like grep or list_dir, so it stops short of a 5.

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

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

Provides some operational guidance – gitignore behavior by default and paging via offset – but never says when to prefer this over grep, list_dir, or read_file. Usage context is implied (file discovery) rather than stated with alternatives.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return format (path:line: text), the default exclusion set (.git, node_modules, .venv, git-ignored files) and the respect_gitignore=false override, plus paging via offset. It omits the regex flavor, multiline behavior, and what happens when max_results truncates output.

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

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

Four short sentences, front-loaded with the core action and return shape, then filtering caveats, then paging. Nothing is repeated and nothing is padding.

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

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

An output schema exists so return values needn't be explained, and the filtering/paging behavior is covered. For a 7-parameter tool with zero schema documentation, though, an agent still cannot predict the effect of max_results, file_glob, or ignore_case from the description.

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 7 parameters, and it only covers about half: pattern (regex), path, offset (paging), and respect_gitignore (explicit). file_glob, ignore_case, and max_results (default 200, a silent result cap) get no explanation anywhere.

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

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

States a specific verb+resource ('Regex search file contents') that cleanly separates it from glob (filenames) and read_file (whole-file reads). The return shape is disclosed up front. It never names the sibling it competes with, so differentiation is implied rather than explicit.

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

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

'Use offset to page' gives one operational hint, and the gitignore sentence tells an agent when results will be unexpectedly filtered. There is no when-to-use/when-not guidance relative to glob, read_file, or query_data, which the agent must infer.

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

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

With no annotations, the description does real work: it discloses that headers are redacted, the body is truncated, and that results are prefixed with PASS/FAIL when assertions are supplied. It omits whether methods are unrestricted, side effects of POST/PUT, and any credential/auth handling, which keeps it from a 5.

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

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

Front-loaded with the core action and outputs, then the assertion extras; each sentence carries information. The expect_json path example is dense but earns its space; a brief parameter-completeness pass would cost little.

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

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

An output schema exists, so return-value explanation is rightly omitted, and the assertion semantics are covered. But for a 13-parameter tool with zero schema descriptions, key calling decisions (body vs json_body, verify_tls, follow_redirects) are left unresolved.

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% across 13 parameters, so the description must compensate. It explains only four of them (expect_status, expect_json with path syntax, expect_contains, max_latency_ms) and leaves the most ambiguous ones—body vs json_body, method, params, headers, timeout, verify_tls, follow_redirects—completely undocumented.

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

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

States a specific verb and resource ("Send an HTTP request") plus the reported outputs (status, timing, redacted headers, truncated body). The parenthetical "localhost and private addresses allowed" implicitly separates it from the sibling web_fetch, so an agent can pick between them without opening 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 localhost/private-address note implies the testing/local reachability use case, and the assertion options hint at smoke-test scenarios. However, it never says when to prefer web_fetch over this tool, nor any preconditions or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions optional auto-fix, which implies file modification, but it does not state that fixes may alter files, whether fixes are safe or unsafe, what permissions are needed, or how configuration is discovered.

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 is appropriately sized for the tool's apparent simplicity.

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?

Although an output schema exists, the description is incomplete for a tool with three undocumented parameters, no annotations, and a fix mode that can mutate files. It should clarify what gets linted, what auto-fix changes, and how path/cwd affect behavior.

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

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

Schema description coverage is 0% for three parameters, so the description must compensate. It only loosely maps 'auto-fix' to the fix parameter and does not explain path (target files/directories) or cwd (working directory), leaving most parameter meaning undocumented.

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: 'Lint Python code with ruff', which is clear and actionable. It does not explicitly differentiate this tool from the related sibling format_code, but the purpose itself is unambiguous.

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

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

The description gives no guidance on when to use this tool versus alternatives such as format_code or run_tests. The parenthetical '(optionally auto-fix)' hints at the fix parameter, but there is no explicit when-to-use or when-not-to-use 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?

No annotations are provided, so the description carries the burden, and it does disclose the trailing-slash convention for directories, which is genuinely useful output-shape context likely not derivable elsewhere. It is silent on non-recursive behavior, error handling for missing paths, symlinks, and ordering, leaving the mutation-free read semantics only implied.

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 compact sentence, front-loaded with the action and immediately followed by the detail that matters for interpreting results. Zero waste.

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

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

For a low-complexity, single-parameter read tool with an output schema handling return values, the description is mostly adequate but leaves the `path` argument's semantics unspecified. A single clause on path resolution would make it complete.

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

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

Schema description coverage is 0%, so the description must compensate for the single `path` parameter. It says nothing about relative vs absolute paths, the default of '.', or whether a file path would error — the only information an agent needs to call it correctly is undocumented.

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

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

Names a specific verb and resource ("List directory entries") and adds an output convention (trailing '/' for directories), so an agent knows exactly what it returns. It does not explicitly distinguish itself from siblings like glob or read_file, which is why it stops short of 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?

There is no guidance on when to use list_dir versus glob (pattern matching) or read_file, nor any statement of prerequisites such as whether the path must exist. Usage is only implied by the verb.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful behavioural trait: that elevated rights may be needed to see other users' PIDs. It does not say whether the tool is read-only (implied), whether results are truncated or paginated on busy hosts, or what happens when privileges are insufficient.

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 capability front-loaded and the caveat second. Every 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?

An output schema exists, so return values need not be explained, and the elevation caveat covers the main operational surprise. But for a 2-parameter tool with zero schema coverage, leaving listening_only's default and protocol's accepted values undocumented is a real gap an agent could trip over.

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

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

Schema description coverage is 0%, so the description must compensate and does not. 'TCP/UDP' hints at the protocol parameter but never states accepted values (the schema declares only a bare string defaulting to 'all'), and listening_only is never mentioned at all despite defaulting to true — a non-obvious default that materially changes the result set.

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

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

States a specific verb and resource: 'List TCP/UDP sockets with owning process.' An agent can tell this apart from list_processes and network_interfaces by the socket-plus-PID framing, though it never explicitly names those near-neighbours.

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 on when to choose this over check_tcp_port, list_processes, or network_interfaces, and no mention of prerequisites beyond a passing note about elevation. The agent must infer the selection criteria from the sibling names alone.

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

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

No annotations are provided, so the description carries the burden. It does disclose the fields returned and the sortable dimensions, but says nothing about permissions, whether the list is a snapshot, error behavior, or whether this enumerates only the caller's processes — meaningful gaps for an uninstrumented 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?

One sentence, front-loaded with the verb and resource, with no wasted text. Density is high but it does so by omitting information rather than by being terse.

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

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

An output schema exists, so return-format explanation is not required. But with 0% schema coverage on three parameters and no annotations, the description should explain the limit/pagination behavior and the name filter, which it does not.

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

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

Schema coverage is 0%, and the description does add real meaning for `sort_by` by pinning the meaningful values to memory/cpu/pid, which the schema leaves as a bare string. However, `limit` (default 25) and `name_contains` filtering are not mentioned at all, so half the parameters remain undocumented.

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 ('List') and resource ('processes') and even enumerates the returned fields (pid, name, user, cpu%, memory). It is unambiguous, though it never states scope such as local vs. remote machine or default sort.

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 says nothing about when to use this tool, when not to, or what alternatives exist. A sibling like `system_info` exists and the boundary between them is left entirely to inference.

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

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

With no annotations, the description must carry the behavioral burden. It usefully discloses the underlying platform mechanisms and platform-specific state values, but it does not mention permissions, scope (all services vs. user services), or other behavioral caveats.

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 compact sentences, front-loaded with the core purpose, and the second sentence adds relevant platform-specific state guidance without any wasted text.

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

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

The tool has an output schema, so return values need not be explained. However, the description leaves `name_contains` undocumented and lacks any guidance about scope or permissions. For a simple two-parameter listing tool it is mostly complete but has a clear gap.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains the `state` parameter with platform-specific examples, but completely omits the `name_contains` parameter, leaving one of two parameters undocumented.

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 services', and immediately clarifies the platform-specific backends (systemd, Get-Service, launchctl). This distinguishes it from related sibling tools such as service_status or list_processes.

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 listing intent is clear, but the description gives no explicit guidance on when to use this tool versus service_status or other service-related tools. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries full behavioral burden. It does disclose the core filtering semantics of language tags and prose handling, which is genuinely useful. It omits side-effect details: whether output_path causes a file write, whether an existing file is overwritten, and whether the tool fails or returns empty when no blocks match.

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, no filler, and the core purpose is front-loaded before the flag semantics. Nothing redundant is included.

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

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

An output schema exists, so return values need not be explained. But for a tool with an output_path that likely writes to disk, the absence of any note about writing behavior, overwrite risk, or failure modes leaves a meaningful gap.

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

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

Schema description coverage is 0%, so the schema gives only names and types. The description compensates for three of five parameters (language, extract_all_blocks, include_prose) but says nothing about 'path' or 'output_path', so full compensation is not achieved.

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

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

States a specific verb and resource ('Extract code from a markdown file'), which is enough to separate it from read_file and script_to_markdown. It does not name those siblings explicitly, so differentiation is left to inference.

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 explains the conditional behavior (fenced blocks only unless extract_all_blocks, prose becomes comments when include_prose), which implies when each flag matters. However, it never says when to choose this over script_to_markdown or pandoc_convert, nor what happens with non-matching files.

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

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

No annotations are supplied, so the description carries the full behavioral burden. The listed fields strongly imply a read-only inspection operation, but the description never explicitly states that it is side-effect free or what permissions are required.

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

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

A single compact sentence with no filler. The key resource and returned data are 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 zero-parameter read tool with an output schema, the description supplies enough context about what information is returned. It falls short only on usage guidance and explicit read-only behavioral disclosure.

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

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

The tool takes no parameters, so the schema does not need parameter documentation. The description appropriately does not invent 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?

Names the specific resource (NIC) and enumerates the exact data exposed: addresses, netmask, MAC, MTU, speed, link state and I/O counters. It is distinguishable from generic siblings like system_info, though it lacks an explicit verb such as 'list' or 'retrieve'.

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 no guidance on when to use this tool versus alternatives such as system_info or list_ports. There is no mention of prerequisites, exclusions, or expected operational 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?

With no annotations, the description carries the full behavioral burden, and it does disclose one important trait: pandoc runs in --sandbox mode, so the document cannot read other files or run filters. It omits other relevant behaviors such as whether output is overwritten, how paths are resolved, or what happens on conversion failure.

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 compact sentences that front-load the core action and then the sandbox caveat. The parenthetical format list is slightly scattershot with the trailing ellipsis, but every sentence contributes.

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

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

An output schema exists so return values needn't be described, but for a four-parameter mutation-style tool with no annotations and zero schema description coverage, the description should do much more. It leaves the from/to format parameters, path semantics, and overwrite behavior entirely unexplained.

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% across four parameters, so the description must compensate and largely doesn't. It lists format names (docx, html, md, rst, pdf) but never maps them to from_format/to_format, doesn't say whether formats are inferred from file extensions when omitted, and says nothing about input_path or output_path behavior.

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

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

States a specific verb and resource (convert documents with pandoc) and enumerates supported formats, so an agent knows exactly what operation is performed. It doesn't explicitly differentiate itself from the sibling convert_data tool, which also does conversion of a different kind, so it falls short of a 5.

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

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

Usage is implied by the format list and the note that PDF output requires a LaTeX engine, which is a useful prerequisite. However, there is no guidance on when to choose this over convert_data, script_to_markdown, or markdown_to_script, and no stated 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?

No annotations are provided, so the description carries the full burden. 'Show' implies a non-destructive read and the sentence enumerates exactly what is disclosed, which is the key behavioral fact here, but nothing is said about permissions, behavior when no policy file exists, or side effects.

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

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

A single tight sentence that front-loads the primary output (policy file path) and then the secondary one (audit log location). No filler or repetition of the name.

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

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

With no parameters and an output schema present, the description need only establish purpose and scope, which it does for all three returned items. Minor gap: no mention of the missing-file / unconfigured-policy case, which is a plausible state for this tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly implies no input is needed.

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

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

Specific verb 'Show' paired with concrete resources: the active policy file path, its contents, and the audit log location. That set of outputs distinguishes it from siblings like read_file or audit_tail, though the description never explicitly says so.

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

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

Usage is only implied by what the tool returns – an agent can infer 'call this to discover policy configuration' – but there is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives such as read_file or audit_tail for related data.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the return shape ('Returns JSON (a list of matches)') and the supported input formats, but it never states that the file is only read and not modified, nor how it behaves on non-matching paths or malformed input.

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, front-loaded with the verb and resource, with examples inline and the return type stated at the end. No wasted text.

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

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

For a simple read-only extraction tool with an output schema present (so return values needn't be spelled out), the description covers purpose, inputs, query syntax, and result type. The main gap is the unexplained optional `format` parameter; otherwise an agent has enough to invoke it correctly.

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

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

Schema coverage is 0% — parameters carry bare titles only. The description compensates substantially for `query` by illustrating path-expression syntax and for `path` by listing supported file types, but it never explains the optional `format` parameter (e.g., whether it overrides extension detection) or clarifies error behavior for `path`.

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

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

States a specific verb and resource ('Extract values from a json/yaml/toml/csv/xml/psd1 file') plus the mechanism ('path expression') and concrete examples. It does not explicitly name or contrast sibling tools like read_file or convert_data, so the agent must infer the boundary itself.

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 examples ('servers[0].name', 'users[*].email') imply the intended use case, but there is no explicit when-to-use statement, no prerequisites, and no named alternatives for cases like raw file reading or format conversion. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses underlying commands and source/level semantics per OS, including the Windows default source and severity levels, but omits permissions/auth requirements and filtering/pagination behavior.

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

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

The description is compact and front-loaded with the core purpose, then efficiently maps platform-specific behavior. Every sentence adds useful information without 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 cross-platform log reader with five undocumented parameters and no annotations, the description is incomplete. It omits key filters such as contains, max_entries, and since_minutes and does not describe macOS source/level behavior, though the output schema covers return values.

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% across five parameters. The description explains source and level semantics for Linux and Windows, but says nothing about contains, max_entries, or since_minutes, leaving three parameters undocumented in both 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 identifies a specific resource, recent system event logs, and documents the platform-specific commands used to retrieve them. It does not explicitly distinguish itself from siblings such as audit_tail, but the resource is clear.

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

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

There is no explicit when-to-use, when-not-to-use, or sibling-alternative guidance. The agent must infer that this tool is for recent OS event logs rather than audit trails or process listings.

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

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

No annotations exist, so the description carries the full burden; it does disclose the important line-numbering contract (1-based, inclusive, -1 sentinel for EOF), which is genuinely useful. It omits other behavioral facts an agent needs: what happens if the path does not exist, whether binary/non-UTF8 files are rejected, and whether large files are truncated.

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 compact sentences with zero filler, and the most error-prone detail (line numbering and the EOF sentinel) is front-loaded right after the purpose.

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

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

An output schema exists, so return value shape need not be explained, and the description covers the one non-obvious calling convention. Missing error/failure semantics and encoding expectations keep it short of a 5 for a filesystem-touching 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 0% (properties carry only titles), so the description must compensate. It meaningfully defines the semantics of start_line/end_line (1-based, inclusive, -1 = EOF), but says nothing about the required 'path' parameter — no indication of relative vs absolute paths or the workspace root convention.

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

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

States a specific verb and resource ('Read a text file'), which clearly separates it from write-side siblings like create_file, edit_file, and replace_lines. It does not however contrast itself with search/listing siblings such as grep or glob, so the differentiation is only partial.

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

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

Usage is only implied by the verb — an agent can infer this is for retrieving file contents rather than searching or listing. There is no explicit when-to-use guidance, no mention of choosing grep/glob instead, and no note on using start_line/end_line to page through large files.

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

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

No annotations are provided, so the description carries the full burden. It discloses the inclusive 1-based range semantics, which is valuable, but does not state that this mutates the file on disk, how existing content is affected, whether the file must exist, or what dry_run does.

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, no filler, and the core range semantics are front-loaded before the insert edge case. 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?

Output schema exists, so return values need not be explained, and the range semantics are covered. But for a mutation tool with zero annotation coverage and 0% schema parameter descriptions, the missing dry_run explanation and file-state assumptions leave real gaps.

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

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

Schema coverage is 0%, so the description must compensate, and it does explain start_line/end_line semantics and the insert trick. However, it says nothing about path or the dry_run flag, leaving two of five parameters — including a behaviorally important one — undocumented anywhere.

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 (replace) and resource (a line range in a file) and clarifies the 1-based inclusive indexing, so the operation itself is unambiguous. It does not differentiate from siblings like edit_file or edit_file_multi, leaving the agent to infer when line-range replacement is preferred.

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

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

It gives one concrete usage rule — end_line=start_line-1 to insert before start_line — which is helpful edge-case guidance. But it provides no context on when to choose this over edit_file/edit_file_multi, no prerequisites (e.g. file must exist), and no mention of the dry_run option.

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

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

With no annotations, the description carries the full burden and does real work: it discloses that the command string is NOT confined and can reach any path the server's user can, which is the single most important safety fact for this tool. It omits other behavioral traits such as timeout enforcement/abort semantics and whether output is truncated.

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, no filler, with the return contract and the critical containment caveat both front-loaded ahead of the path defaults.

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

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

An output schema exists, so return values needn't be explained, and the containment warning covers the main risk of an unannotated mutation tool. The remaining gap is timeout behavior, which matters for a shell tool but is not addressed in text or schema descriptions.

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. It explains cwd well (inside the workspace, defaults to workspace root) and the command param is self-evident, but the `timeout` parameter is never mentioned in the description and its schema entry has no description text either.

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?

Specific verb+resource ("Run a shell command") plus the return contract ("exit code, stdout and stderr"), which tells an agent exactly what it gets back. It does not differentiate itself from siblings like run_tests, lint, grep, or glob, which are the obvious alternatives for the same general tasks.

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 constrains the working directory ("must be inside the workspace", default root) but gives no explicit when-to-use/when-not guidance relative to specialized siblings. An agent must infer on its own that run_tests or grep should be preferred for their specific jobs.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose how cwd affects execution, whether output is captured, how failures are reported, or whether there are timeouts or side effects.

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

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

The single sentence is front-loaded with the core action and includes a useful example. It is efficient and contains 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?

Although an output schema exists, the description is too thin for a 3-parameter execution tool with no annotations. It omits cwd semantics, execution environment, failure behavior, and timeout or safety 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 only partially compensates: it explains path and gives an example for args, but cwd is entirely undocumented despite being a key execution parameter.

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

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

The description states a specific verb and resource: run pytest on a path. An agent can distinguish this from generic run_command or lint, though it does not explicitly name those siblings.

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

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

There is no guidance on when to use this versus run_command, lint, or format_code, nor any prerequisites or exclusions. The example args hint at filtering but do not establish usage conditions.

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

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

No annotations, so the description carries the full burden. It usefully discloses that the conversion is heuristic (i.e. lossy/imperfect) and spells out the comment-vs-code rule, which is real behavioral value. It says nothing about whether output_path writes to disk or overwrites an existing file, or what happens to encoding/BOM, which matters for a file-touching 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?

Three tight sentences with the core behavior front-loaded and no filler; the PowerShell <# #> parenthetical and the reversal note each add information. Minor cost: the middle clause is a dense run-on.

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

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

An output schema exists, so return values need not be explained, and the transformation semantics are well covered. However, for a three-parameter file-writing tool with zero schema documentation and no annotations, the description leaves the output_path/language behavior entirely unexplained.

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% — all three parameters (path, language, output_path) are bare titles with no descriptions. The description never mentions any parameter, so it fails to clarify the most consequential ambiguity: whether output_path causes a file to be written or the markdown is returned. Only the implicit 'script' wording hints at what path is.

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

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

States a specific verb and resource — 'Convert a script into literate markdown' — and even explains the transformation rule (column-0 comments and PowerShell <# #> blocks become prose, the rest becomes fenced code). It names its inverse sibling markdown_to_script, but does not distinguish itself from pandoc_convert, which also converts formats.

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?

'Heuristic and meant for documentation' implies the intended context, and naming markdown_to_script as the reversal hints at the round-trip use case. There is no explicit when-not guidance or routing advice versus pandoc_convert, so usage must be inferred.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It implies a read-only inspection but does not state permissions, side effects, error behavior, or what the detailed status contains.

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 efficient sentence with no wasted words and the resource scope front-loaded. Its brevity contributes to the gaps elsewhere but the sentence itself is well-structured.

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

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

An output schema exists, so return details need not be explained. However, for a tool with no annotations and an undocumented required parameter, the description is too thin to fully guide correct invocation or distinguish it from list_services.

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

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

The single required parameter 'name' has 0% schema description coverage, and the description does not explain the service name format or how it identifies a service. It adds little meaning beyond the field name.

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

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

The description states a clear operation on a specific resource: retrieving detailed status for a single service. It implicitly distinguishes itself from the sibling list_services by specifying 'one service,' though it does not name that alternative or clarify what 'status' includes.

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

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

There is no explicit guidance on when to use this tool versus list_services or other service-related tools. The single-service scope is implied, but exclusions, prerequisites, and alternatives 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?

No annotations exist, so the description carries the full burden; the field list implies a harmless read-only snapshot with no parameters, which is reasonable but never stated. It doesn't say whether values are point-in-time, whether the call is expensive, or whether elevated permissions affect what is reported (e.g. swap or disk detail).

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 compact sentence that front-loads the most distinguishing fields and wastes no words. The only weakness is that it is a comma-list fragment rather than a sentence with a subject and verb, which reads slightly less crisply than it could.

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 an output schema is present and there are no parameters, the description only needs to signal the domain and scope, which it does. Enumerating the returned fields is partly redundant with the output schema, but it makes the tool identifiable at a glance, and no safety or side-effect information is required for a no-arg read.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies there is nothing to configure, and the schema confirms an empty argument object.

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?

Enumerates the exact resource it retrieves (OS, kernel, uptime, CPU, load, memory, swap, disk) and scopes it to 'this machine', which implicitly separates it from workspace_info or environment_variables. It lacks a verb, so the action (retrieve a snapshot) must be inferred from the noun list, and no sibling is named explicitly.

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

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

There is no statement of when to reach for this tool versus list_processes, environment_variables, workspace_info, or service_status, all of which live in the same sibling set. Usage is only inferable from the field list, and no exclusions or prerequisites are given.

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

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

With no annotations, the description carries the full burden. It does disclose two useful traits beyond the name: the new item defaults to 'pending' and the call returns the updated list. It omits whether writes persist across sessions, whether duplicates are allowed, and ordering behavior — meaningful gaps for a mutation tool with zero 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?

One sentence, front-loaded with the verb and resource, with the return behavior appended where it belongs. Nothing is wasted and nothing needs to be cut.

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

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

An output schema exists, so return values needn't be detailed, and the tool is trivially simple at one required parameter. The remaining gap is minor: no statement about duplicate handling or where exactly the scratchpad lives relative to workspace_info.

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

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

Schema coverage is 0% and the sole parameter 'text' is undocumented in the schema, so the description must compensate. It only implies the parameter by describing the tool's effect ('add a todo'), giving no guidance on content format, length, or whether multi-line text is accepted.

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 ('Add') and resource ('a todo') plus the default state ('status pending') and target store ('workspace scratchpad'). The verb cleanly separates it from siblings todo_list, todo_update, and todo_remove without needing to name them.

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

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

Usage is only implied through the verb contrast with todo_update/todo_remove; there is no explicit 'use this when...' statement, no preconditions, and no mention of what to do if the item already exists.

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

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

No annotations are provided, so the description carries the burden, and 'List' does signal a non-mutating read. It names the filter values, but omits what happens when status is omitted (all statuses? only open ones?), the sort order of results, and whether completed items are included by default. Since an output schema exists, return shape need not be described, but the default-filter behavior is a real gap.

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

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

Two short sentences with the resource front-loaded and the filter detail second. Every clause carries information; there is no filler or restatement of the tool name.