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

Goes well beyond the annotations by disclosing the sampling dependency, the NO_CONTEXT requirement for an MCP client that injects Context, the SAMPLING_ERROR failure mode, and a full return/error envelope. The remaining gap is the unexplained interaction between the "no tools" claim and the required available_tools parameter, which leaves the execution model ambiguous.

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 mechanism in sentence one, then organized under clear headers (Return Format, Recovery, Examples). "Args: See Parameters block." is pure filler, and the duplicated Return Format block is partly redundant with the existing output schema, but overall it is well-structured rather than bloated.

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 restating the return shape is optional, and the failure/recovery paths are well covered for a tool with a sampling dependency. What's missing is any description of max_iterations semantics or the delegation behavior behind available_tools, which an agent needs to invoke this correctly.

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

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

Schema coverage is 0% and the description explicitly defers with "Args: See Parameters block," adding nothing for workflow_prompt or max_iterations (max_iterations is never mentioned at all). Only the examples give indirect shape to workflow_prompt and available_tools, which is insufficient for three undocumented parameters on a non-trivial tool.

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

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

The description explains the mechanism (server-side context gathering plus ctx.sample()) and gives illustrative examples, but the actual capability is fuzzy: it says "no tools" yet takes an available_tools list and one example renames files, so it's unclear whether this analyzes files or performs file operations. It also never distinguishes itself from siblings like file_ops, dir_ops, or search_ops, which the examples reference.

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 compatibility note ("Compatible with Claude Desktop which supports basic sampling but not sampling.tools capability") and the two examples imply a usage context, and the Recovery section gives error-conditional guidance. However, there is no explicit rule for when to pick this tool over calling file_ops/search_ops directly, which is the key decision an agent faces given the siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that stderr is captured and returned in a structured envelope, which hints at failure visibility, but it never says what happens when validation fails (success=false? exception?) — despite an output schema already documenting the 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?

The purpose line is front-loaded and the examples are compact and useful, but "Args: See Parameters block." is a zero-information sentence and the Return Format block largely restates an output schema that already exists. Roughly a third of the text does not earn its place.

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

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

For a tool whose parameters are entirely undocumented, the description should carry the load and does not: path semantics, timeout behavior, and the effect of validate=true are all left to guesswork. The examples and return envelope are helpful, but an agent still cannot confidently predict what validation means here.

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 have only types and defaults. The description deflects with "See Parameters block" and then provides no meaning for `timeout` at all, and no explanation of what `validate` toggles or whether `path` is a directory or a compose file. The two examples only weakly illustrate `path` and `validate=False`.

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

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

The description names a specific verb pair and resource ("Render and validate compose configuration") and anchors it to the real command "docker compose config". That distinguishes it from sibling compose tools like compose_up/compose_down/compose_logs, though it never explicitly states that it does not start containers.

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, no mention of alternatives (e.g. use compose_up to actually launch), and no prerequisites. "Args: See Parameters block." is the only nod to usage, and the examples show call shapes rather than decision criteria.

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?

Goes well beyond the annotations by naming what is removed (containers), what failure looks like (bind mounts in use), and how to recover. The annotations declare destructiveHint=false, and while removal is recoverable via compose_up, the description never warns that volumes_prune=True deletes persistent volume data — the one truly irreversible action here is undisclosed.

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

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

Front-loaded with the core action, then recovery, then return format and examples — a sensible priority order with no filler prose. The return-format block is partly duplicated by the existing output schema, so a little trimming is possible.

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?

Safety-relevant context (recovery on failure) is present and the output shape is covered, but for a zero-required-parameter, 0%-schema-coverage mutation tool it leaves meaningful gaps: the meaning of remove_orphans, the timeout behavior, and the data-loss implications of volumes_prune.

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 does not: 'timeout' (300s) and 'remove_orphans' (default true, which silently deletes non-compose containers) are never mentioned, and path/volumes_prune appear only as bare example arguments with no explanation of effect or data risk.

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 pair and resource ('Stop and remove Compose containers') and anchors it to the canonical CLI equivalent ('docker compose down'), which lets an agent distinguish it from compose_up, compose_restart, and compose_ps without opening a schema.

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

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

Gives a recovery path for failure ('stop consumers or use docker CLI for force removal'), which is genuine when-it-fails guidance. But it never says when to prefer compose_down over compose_restart (a sibling that also stops containers) or what happens to running services not managed by the compose file.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a recovery path and return shape, but omits the most consequential behavior: that follow=true likely streams/blocks, and that timeout=300 acts as the guard — an agent could hang without knowing this.

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 purpose sentence, then recovery, return format and examples in clearly labeled blocks — easy to scan. The return-format block duplicates the existing output schema, so it costs space without adding much, but the overall size is proportionate.

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?

Since an output schema exists, the description needn't restate return values, yet it does while leaving half the input parameters undocumented. For an 8-parameter tool with a blocking-streaming mode, the description is adequate but has clear gaps an agent would fall into.

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% across 8 parameters, so the description carries the full burden and largely fails it. Examples illustrate path, tail, services and since, but follow, timeout, until and timestamps are never explained — and these are the parameters whose semantics matter most.

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 ("Fetch service logs (docker compose logs)"), which is unambiguous on its own. It does not, however, contrast itself with siblings like container_ops or compose_ps beyond the recovery note, so an agent must infer where compose logs ends and container logs begin.

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 explicit failure-path guidance: "If logs empty, verify service names with compose_ps", naming the alternative and the condition that selects it. It lacks any when-not guidance (e.g. when to prefer container_ops or when follow is appropriate), so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds the return envelope shape but nothing about behavior such as what happens when no containers are running, whether it auto-creates a project, or how the timeout interacts with a slow stack.

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 core purpose is front-loaded in the first line, followed by clearly headed return-format and example blocks. Slightly wasteful: the Return Format section largely restates the output schema and takes as much space as the actual behavioral content.

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

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

For a zero-required-parameter read tool with rich annotations and an output schema, the essentials are present, but the two undocumented parameters (timeout, services) are a real gap an agent could stumble on. The space spent duplicating the output schema would have been better used explaining those inputs.

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 carry all four parameters, yet it only illustrates `path` and `all_services` via examples. `timeout` (default 120) and `services` (array filter) are never mentioned anywhere, leaving half the parameters semantically opaque.

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 (compose services) and anchors it to the exact underlying command (`docker compose ps --format json`), which makes the scope unambiguous. Against siblings like compose_logs, compose_config, and compose_up, an agent can immediately tell this is the service-status lister.

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 two examples (`path=...` and `all_services=True`), which show typical call shapes but never state when to pick this over compose_config or compose_logs, nor any preconditions (e.g. the project must already be running). No exclusions or alternatives are named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is carried by structured data. The description adds the success/failure response shape, but says nothing about downtime, whether containers are recreated, or what happens to in-flight work — the traits that matter most for a non-idempotent restart.

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 one-line purpose followed by return format and examples — every block is scannable and none is filler. The return-format block is somewhat redundant given an output schema exists, costing a point.

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 3-parameter mutation tool with zero schema coverage, the definition is workable but thin: it never explains `timeout` or the all-services default, and gives no indication of restart scope or side effects. The return-format section does relieve pressure on describing outputs.

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 only partially does: the examples show that `path` locates the compose project and that `services` optionally narrows scope, but no parameter is explained. `timeout` is never mentioned, and the behavior when `services` is null (restart everything?) is left to inference.

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 — restart compose services — and anchors it to the canonical equivalent (docker compose restart). An agent can distinguish it from compose_up/compose_down/compose_ps by the verb alone, though the description never explicitly contrasts 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?

Usage is only implied through two examples (restart whole stack via path, or a subset via services). There is no explicit guidance on when to restart versus compose_down + compose_up, nor any stated prerequisites such as requiring a running stack.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds real value with a build failure/port conflict recovery path and the note that re-running may recreate containers per compose semantics (consistent with idempotentHint=false). It still doesn't mention permission requirements or that detach defaults to true.

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

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

Front-loaded with the core action, then recovery, idempotency, return format, and examples in scannable sections. The return-format block is largely redundant given the output schema exists, slightly reducing density but not hurting comprehension.

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 restating return shape is unnecessary, and the mutation/recovery context is covered. The remaining gap is the undefined semantics of half the parameters (detach, timeout, scale) plus no note on permissions for a container-mutating operation.

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 6 parameters, and the examples only illustrate path, services, and build. Meaning of detach (default true), timeout (default 300), and scale is left entirely to inference, so the description only partially compensates for the schema gap.

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

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

The description opens with a specific verb and resource ('Start Compose services (docker compose up)'), which is unambiguous. It doesn't explicitly distinguish itself from siblings like compose_restart or compose_down, but the word 'Start' plus the literal command mapping makes selection clear enough.

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

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

It provides recovery guidance after a failed build or port conflict and an idempotency note, which implies when it's appropriate to (re)run. However, there is no explicit statement of when to use this versus compose_restart or compose_down, so the agent must infer boundaries.

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

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

The annotations declare destructiveHint=false, yet the description explicitly lists remove_container and stop_container, which are destructive lifecycle operations. The description also does not disclose irreversible deletion, force semantics, permission requirements, or the danger of calling remove_container.

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 front-loaded with the operation list, then return format and examples, so it is easy to scan. The line 'Args: See Parameters block' is wasted space, but the overall structure is efficient and not 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?

For a 10-operation, 28-parameter tool, the description omits critical operation-specific parameter requirements and destructive behavior details. It does provide the operation list and return format, and an output schema exists, but that is not enough to guide correct invocation of a complex multi-operation 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?

There are 28 parameters with 0% schema description coverage, and the description mostly defers with 'Args: See Parameters block.' The examples mention only a few parameters (show_stats, container_id, tail, timeout) and do not explain operation-specific applicability for the remaining parameters.

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

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

The description states the resource and scope clearly: 'Docker Container Lifecycle operations,' followed by an explicit operation list. It does not, however, distinguish this tool from overlapping siblings such as compose_up or host_ops, so sibling differentiation is incomplete.

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 operation list and examples imply when individual operations are useful, such as checking logs or restarting a container. But there is no explicit guidance on when to use this tool versus compose_up, compose_down, or other siblings, and no exclusions or prerequisites 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?

The description lists operation names and a return envelope but discloses no actual behavior: whether remove_directory recurses or fails on non-empty directories, what `mirror` and `overwrite` do to existing destinations, what `dry_run` previews, what the robocopy vs shutil engine selection implies, or what `timeout` governs. Moreover, the enumerated `remove_directory`/`move_directory` operations conflict with the declared destructiveHint=false, so the safety profile an agent reads from annotations is wrong.

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?

Headers and a compact example block give it a front-loaded, scannable shape, and the operation list is efficient. However, the 'Args: See Parameters block.' line is pure waste, and the Return Format section largely restates the output schema that already exists.

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

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

For an 18-parameter, eight-operation mutation tool with zero schema descriptions, the description needs to at least map parameters to operations and flag which combinations are risky; it does neither. The output schema being present excuses the return-format brevity, but the invocation-side gaps (engine choice, dry_run scope, mirror/overwrite interactions, destination_path) are large.

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 18 parameters, and the description's only nod to them is 'Args: See Parameters block.' — a pointer to a block that contains no descriptions. Only path, operation, max_depth, recursive, and human_readable appear incidentally in examples; engine, mirror, dry_run, pattern, timeout, exist_ok, max_files, overwrite, output_format, create_parents, include_hidden, destination_path, and exclude_patterns are undocumented everywhere, including which ones apply to which operation.

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 opening line names the resource (directory structure) and the description enumerates all eight supported operations explicitly, so an agent can see the full verb set at a glance. It does not distinguish itself from the sibling `file_ops` or `search_ops` (file-vs-directory scope, listing vs searching), so the sibling differentiation is left implicit.

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 show three calls but never say when to pick one operation over another, when to prefer this over `file_ops`, or when a directory operation is unsafe/inappropriate. Nothing signals that remove_directory, move_directory, or copy_directory with mirror=True are destructive paths requiring care, and there are no stated preconditions.

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

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

The description includes delete_file among supported operations while annotations declare destructiveHint=false, a direct contradiction of the destructive safety signal. Although concurrency-safe writes and return/failure shapes add useful context, the annotation contradiction caps this dimension.

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 well structured, front-loading operations and then covering line indexing, write safety, return format, and examples. The phrase 'Args: See Parameters block' is wasted, and the return-format section partly duplicates the output schema, but overall it is efficient for such a large 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 29-parameter multi-operation tool with no schema parameter descriptions, the definition omits operation-specific parameter requirements and destructive/backup behavior. The output schema and return-format section help, but they do not compensate for the missing operational detail.

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

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

Schema description coverage is 0% for 29 parameters, yet the description explains only offset/limit line indexing and a few examples. It leaves most parameters, including content, overwrite, no_backup, and the ambiguous old_str/new_str versus old_string/new_string fields, undefined.

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

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

The description states the resource and enumerates the 18 file operations, so the tool's scope is clear. It does not, however, distinguish this from siblings like dir_ops or search_ops.

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 lists operations and examples but gives no explicit when-to-use/when-not guidance or routing against sibling tools such as dir_ops and search_ops. Selection between operations 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: locks are per-path and span multiple client sessions, which explains why the tool exists. It does not discuss lock staleness or scope limits, which keeps it from a 5.

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

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

The purpose statement and the debugging rationale are front-loaded and earn their place. The '## Return Format' block duplicates the existing output schema, and the '## Examples' section contains only a bare no-argument call, which is filler for a zero-parameter 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?

An output schema exists, so return values need not be spelled out, and the description still names the key fields. For a zero-argument diagnostic read, an agent has everything needed to call it correctly; only edge-case behavior (stale locks, empty results) is unaddressed.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the example call 'get_lock_status()' confirms no arguments are needed. Baseline for a parameterless schema applies.

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

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

States a specific verb and resource: 'Get current per-path file lock status', with the parenthetical '(diagnostic tool)' clarifying its intent. It is clearly distinguishable from the file/dir/host operation siblings, though it does not explicitly contrast with the nearest sibling, test_concurrency_safety.

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

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

Gives a concrete usage context: 'useful for debugging concurrent write contention between Claude Desktop, Cursor, and Windsurf sessions.' However, it offers no when-not-to-use guidance and never mentions test_concurrency_safety, which appears to be the adjacent diagnostic sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a return envelope and two result shapes, but the example host_ops(operation="get_system_info", detailed=True) references a parameter absent from the schema, which can mislead invocation.

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 sectioned and front-loads the host-context purpose, but the 12-operation list duplicates the enum in the schema, 'Args: See Parameters block' is wasted text, and the invalid example consumes space without helping invocation.

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

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

This is a complex 12-operation dispatcher with four undocumented parameters and substantial sibling overlap, so the description needs more parameter and selection context. Output schema exists, so return values need not be fully explained, but the missing per-parameter semantics and alternative guidance leave it 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% for four parameters, and the description punts with 'Args: See Parameters block.' It gives one category example for get_help but never defines level, tool_name, or the meaning/range of category, and the detailed=True example is not a valid 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 names host system context and enumerates the specific get_* operations, so the agent can tell it retrieves host information. It does not differentiate these operations from overlapping monitor_* siblings such as monitor_get_system_status and monitor_get_cpu_info.

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

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

The description provides no when-to-use or when-not-to-use guidance, and it never mentions the monitor_* alternatives that retrieve similar system data. The examples show invocation syntax for two operations but do not explain selection criteria.

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

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

The annotations declare destructiveHint=false, but the description explicitly lists remove_image, prune_images, remove_network, prune_networks, remove_volume, and prune_volumes, which are destructive operations. This directly contradicts the annotation and is a serious safety-signaling inconsistency.

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 uses clear sections for operations, return format, and examples, with the main domain and operation list front-loaded. It is reasonably concise for a multiplexed tool, though 'Args: See Parameters block' adds little value.

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

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

For a 16-operation, 28-parameter tool, the description lists operations and gives a few examples but does not explain operation-specific parameter requirements or safety implications. The output schema exists, but the missing parameter mapping and contradictory destructive hint leave the agent under-equipped.

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

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

There are 28 parameters with 0% schema description coverage, and the description mostly says 'Args: See Parameters block.' The examples clarify only a few fields such as all_images, image, tag, name, and driver, leaving most operation-specific parameters undocumented in both the schema and the description.

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

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

The description clearly identifies the tool as covering Docker Images, Networks, and Volumes operations and lists the supported operation names. It is specific about the resource domain but does not explicitly differentiate itself from siblings such as container_ops or compose_*.

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 operation list and examples imply when the tool is applicable, particularly for image, network, and volume operations. However, there is no explicit guidance on when to choose this tool over siblings like container_ops, compose_up, or host_ops, nor are exclusions or prerequisites stated.

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

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

Annotations already establish this as a read-only, idempotent, non-destructive, closed-world query. The description adds useful behavioral detail by disclosing the exact result shape and noting that frequency may be absent.

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

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

It is front-loaded with the core purpose, then gives the return format and a minimal example. There is no filler or redundancy.

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

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

For a zero-argument read-only tool with annotations and an output schema, the description is complete enough to call correctly. It even includes the return shape, making the result fully predictable.

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

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

The tool has zero input parameters, so the baseline is 4. The description does not need to explain inputs, and its mention of optional frequency refers to the return value rather than an input 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 resource and returned data: physical/total core counts, optional frequency, and per-CPU usage. It is clear but does not explicitly differentiate itself from nearby monitoring siblings like monitor_get_resource_usage or monitor_get_system_status.

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

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

The description gives no guidance on when to use this CPU-specific tool versus the other monitoring tools. The example only shows an empty invocation, not a usage context or alternative.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the bar is lower. The description nevertheless adds real value by disclosing that mounts raising PermissionError are skipped, meaning results can be a partial partition list — a behavior not visible in any structured field.

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 purpose in a single clause, and the sections are clearly delimited. The Return Format block is largely redundant given an output schema exists, which costs a little space.

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

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

With zero params, full annotation coverage and an output schema present, the definition covers what an agent needs to call it. The one remaining gap is that the 'usage' field's unit (percent vs bytes) is never stated anywhere.

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

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

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The example call correctly reinforces that no arguments are needed.

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

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

States a specific verb+resource: per-partition disk usage, which is clearly distinguishable from siblings like monitor_get_memory_info or monitor_get_cpu_info. It doesn't explicitly contrast with monitor_get_resource_usage or monitor_get_system_status, which may also surface disk figures.

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 statement of when to use this versus the other monitor_* tools, and no prerequisites or exclusions. The PermissionError note describes behavior during execution, not when to select the tool, so the agent must infer selection 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?

Annotations already declare this as read-only, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds the virtual/swap split and a return-shape example, but does not add deeper behavioral context such as cost, latency, or scope limitations.

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 short and front-loads the purpose. The Return Format section duplicates the existing output schema, and the example call is trivial for a no-parameter tool, but neither is verbose enough to be a major flaw.

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 a simple no-parameter, read-only tool with full annotations and an output schema, the description is largely complete. The main remaining gap is the absence of sibling differentiation against broader resource-usage tools.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The baseline for zero-parameter tools is appropriately met.

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

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

The description clearly states the resource and scope: virtual and swap memory breakdown. It is more specific than a generic system-status call, but it does not explicitly distinguish itself from sibling monitor_get_resource_usage or monitor_get_system_status.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as monitor_get_resource_usage or monitor_get_system_status. Use is only implied by the tool name and the phrase 'memory breakdown'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds the return envelope shape (success/result with io_counters, addresses, stats), which is modest extra context since an output schema already exists.

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

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

Front-loads the purpose in one sentence, then uses headed sections for return format and example, so an agent can scan it quickly. The Return Format block slightly duplicates the output schema but stays compact.

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

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

For a no-argument read-only network info tool with both annotations and an output schema, the description is sufficient to call it correctly. It could add one line on when network data is the right choice versus other monitor_* tools.

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

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

The tool takes zero parameters, so there is nothing for the description to document; the baseline of 4 applies. The example call with empty parentheses correctly reinforces that no arguments are 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?

Names a specific verb ('aggregate') and resource ('I/O counters, per-interface addresses and stats'), making clear it is the network-monitoring sibling among monitor_get_* tools. It does not explicitly contrast itself with those siblings, but the resource naming is specific enough to distinguish.

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

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

The description states what the tool returns but never says when to call it, when not to, or which sibling (e.g. monitor_get_performance_metrics vs monitor_get_system_status) to prefer. An agent must infer that this is the network-specific monitoring call.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive, non-open-world operation, so the safety profile is covered. The description adds useful return-shape context via the Return Format block, but does not disclose permissions, rate limits, or other operational behavior beyond that.

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

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

The description is front-loaded with the core purpose in one sentence, then provides return format and an example. It is appropriately short, though the Return Format block is somewhat redundant given that an output schema already exists.

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

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

For a zero-parameter, read-only metrics tool with rich annotations and an output schema, the description covers what is needed to invoke it correctly. Its main gap is the lack of sibling differentiation, which would help an agent choose this aggregated performance tool over the narrower CPU, memory, disk, or network tools.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The description implicitly confirms this with the empty-call example monitor_get_performance_metrics().

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 ("get performance metrics") and names the concrete counter categories: CPU times, memory, swap, disk I/O, and network I/O. It does not differentiate this aggregated performance view from sibling tools like monitor_get_cpu_info, monitor_get_memory_info, monitor_get_disk_usage, or monitor_get_network_info.

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

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

The description gives no guidance on when to use this tool versus the many narrower monitor_get_* siblings. It states what data is returned but provides no usage context, alternatives, 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely useful runtime context: AccessDenied on some PIDs is normal and total_matching reflects the filtered list, which an agent could not infer from the schema.

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

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

Front-loaded one-line purpose followed by compact recovery and return-format sections. The 'Args: See Parameters block' line is mild filler, and the return-format block partly duplicates the output schema.

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

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

For a 4-param read-only listing tool with an output schema, the description covers purpose, filtering behavior, and a useful recovery note. The main gap is that sort_order and parameter defaults are not described anywhere readable.

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 four parameters (sort_by, sort_order, max_processes, filter_pattern) are undocumented in structured fields. The description names filter_pattern and the examples demonstrate max_processes and sort_by, but sort_order and defaults are never explained 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?

States a specific verb ('List') and resource ('running processes') plus the filtering scope. It is distinguishable from monitor_* siblings like get_memory_info or get_cpu_info, though it doesn't explicitly contrast with 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?

The examples imply practical usage (limit results with max_processes, filter with filter_pattern), but there is no explicit when-to-use guidance versus siblings such as monitor_get_performance_metrics or container_ops.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so "Read-only; safe to retry" merely restates structured data. No additional behavior is disclosed (e.g., cost of sampling, whether values are instantaneous vs averaged, host scope).

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

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

The opening is a noun fragment rather than a front-loaded verb phrase, and the full '## Return Format' JSON block plus an empty '## Examples' line consume most of the text while duplicating the declared output schema. The content is short in absolute terms but poorly allocated.

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

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

With an output schema present, the return-format section is redundant, and given a crowded sibling set the definition is missing the one thing that matters: scope relative to the per-resource monitor tools. It is callable but under-specified for correct tool selection.

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 the baseline is 4. The description correctly implies no inputs are needed via the empty-call example, and there is nothing left to disambiguate.

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 fragment "CPU, memory, root disk usage, and boot time" identifies the resources read but supplies no verb or object noun ('usage' is only implied by the tool name). It also fails to distinguish itself from obvious siblings like monitor_get_cpu_info, monitor_get_memory_info, monitor_get_disk_usage, and monitor_get_performance_metrics, so an agent cannot tell whether this is an aggregate or a duplicate.

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

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

There is no statement of when to use this aggregate monitor versus the per-resource siblings (cpu/memory/disk/performance), which is the primary ambiguity here. The only conditional-looking line is the idempotency note, which is not 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?

The readOnlyHint/idempotentHint/destructiveHint=false annotations already define the safety profile, and the description adds real value on top: it discloses the returned sections and a concrete failure-mode recovery path for psutil AccessDenied. It does not state cost/latency or whether include_processes materially slows the call, which is the main remaining 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?

The lead sentence is well front-loaded and the recovery note is genuinely useful, but the verbatim Return Format block largely duplicates the output schema and consumes a lot of space. The examples are helpful for parameter usage, though one more line on defaults would have earned that space better.

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

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

For a no-required-parameter read tool with annotations and an output schema, this is close to complete: it explains what is collected, what the response looks like, and how to recover from permission errors. The missing piece is positioning against the granular monitor_get_* siblings, which matters given a 24-tool namespace.

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 partially does: it mentions optional disk, network and top processes, and the example shows include_processes and max_processes=20. include_disk is never named directly, defaults are not restated, and the meaning/upper bounds of max_processes (what counts as a 'top' process) is never explained.

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 opening sentence names a concrete resource set (OS, CPU count, load, memory, disk/network, top processes) and frames the tool as a single-file 'snapshot', which implicitly separates it from the single-metric siblings monitor_get_cpu_info, monitor_get_memory_info and monitor_get_disk_usage. It never states that distinction explicitly, so the agent must infer it from the aggregate field list.

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

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

There is no statement of when to call this aggregate snapshot versus the many granular monitor_get_* siblings, and no prerequisite notes. The only conditional guidance is a recovery hint (AccessDenied → retry with fewer options or elevate permissions), which addresses failure handling, not tool selection.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds valuable behavior ('search_files ... never looks at file content') and partial return shapes. But it is silent on risky-looking surface like fix=true, run_linter, and early_exit, leaving real behavioral questions unanswered against a declared read-only contract.

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?

Structure is good: operations list first, then the critical pattern semantics, then return format and examples. But it is marred by duplicated text ('find_todos, find_symbols, validate_json.' appears twice) and by return-format detail for only 3 of 13 operations while examples carry more weight than prose should need to.

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 13-operation, 22-parameter dispatcher with zero schema description coverage, the description is far short of what an agent needs to invoke operations correctly — there is no per-operation parameter mapping and no mention of output for ten operations. An output schema exists, so return-value explanation is largely unnecessary, yet the agent still cannot tell which parameters apply to which operation.

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 22 parameters, and the description dismisses them with 'Args: See Parameters block,' which supplies no meaning. Only search_pattern, path, and min_size_mb get any explanation (via the semantics note and an example); the remaining parameters, including fix, hash_algorithm, log_levels, start_time/end_time, and max_duplicates, are 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 names a specific verb family and resource ('Content Analysis, Grep, and Comparison operations') and enumerates all 13 supported operations, so an agent knows the capability surface. It does not, however, distinguish itself from siblings like file_ops or dir_ops, so the boundary with those tools stays ambiguous.

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 'Pattern semantics' section gives a real when-to-use rule between two operations (content regex for grep_file/count_pattern vs filename glob for search_files, plus the recursive=True escape hatch). There is no guidance for when to pick this tool over file_ops/dir_ops, no exclusions, and no guidance for the other eleven operations.

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?

Goes beyond the destructiveHint annotation by explaining the mechanism: a short delay so in-flight responses can flush, plus a concrete return payload with shutdown_in_seconds. It does not say whether the process can be restarted by the agent or whether connections are dropped, so it stops short of full disclosure for a destructive 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?

Front-loaded with the core action and mechanism, then structured with clear headings. The Return Format and Examples sections are somewhat redundant given an output schema exists and there is only one trivial parameter, but nothing is bloated.

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 destructive tool, the description covers scope, mechanism, and return shape. An agent has enough to call it correctly; only the confirm=false behavior and post-shutdown recovery expectations are unstated.

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 `confirm` parameter has no description. The example `server_shutdown(confirm=True)` hints that confirm gates the action, but the description never states what confirm=false (the default) does — presumably a no-op — leaving the most consequential semantic implicit.

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 (shut down the filesystem-mcp server process) and scopes it as an orderly exit. This is clearly distinct from siblings like compose_down or file_ops, which act on containers or files rather than the MCP server 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?

Explicitly states the target context: 'Intended for the HTTP daemon; stdio instances exit when the parent closes the stream anyway.' That tells an agent both when to use it and when it is pointless, which is exactly the routing information needed.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description adds meaningful context by clarifying the writes target a temp file and that corruption is the observable signal, so an agent understands the blast radius. It does not mention runtime cost or that the result may be nondeterministic, so it falls short of full disclosure.

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

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

Purpose is front-loaded in the first sentence, with the semantics of the simulated load right after. The return format block duplicates the existing output schema, which is slightly wasted space, but the examples justify themselves.

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

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

An output schema exists, so the return-format section is redundant rather than necessary; the absence of any contention/timeout expectations or guidance on interpreting concurrency_safe=false is the main remaining gap. For a two-parameter diagnostic tool, this is largely complete.

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

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

Schema coverage is 0%, so the description carries the burden—and it does partially by revealing the operation values 'write' and 'edit' via examples and showing plausible num_clients values. It still never documents the default values (write, 5) or bounds on num_clients, but it adds real meaning beyond the bare schema.

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

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

States a specific verb and resource: tests that file_ops write/edit locking prevents corruption under concurrent load. This clearly distinguishes it from get_lock_status (which reports status) and file_ops (which performs the operations).

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?

Explains what the test simulates but never states when an agent should run this test versus checking get_lock_status or invoking file_ops directly. Usage is implied by the 'test' framing rather than stated, and no alternatives are named.

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