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 adds real value: it discloses the cross-platform, in-process implementation (consistent behavior with no external binary) and a security-relevant guard for extract. It does not cover what 'list' returns, permission/auth requirements, or how overwrite/skip semantics interact, but the core traits an agent needs are present.

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 no filler: capability and formats first, then the implementation trait, then the safety/behavior note. Every clause earns its place and the most important information is front-loaded.

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

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

For a 15-parameter tool with no annotations and no output schema, the description is adequate but incomplete: it never mentions the gzip/gunzip actions that the schema declares, nor what 'list' produces, leaving the agent to reconcile actions between description and schema. The 100% schema coverage and the extract safety note keep it at minimum viable rather than deficient.

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

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

Schema description coverage is 100%, so the schema already documents all 15 parameters in detail. The description adds only marginal framing: that 'create' accepts either a directory or a file list with glob filters, and that extract path-escapes are rejected. That is a baseline 3 when the schema does the heavy lifting.

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 concrete verbs (create, list, extract) and the exact resource and formats (zip, tar, tar.gz/tgz, plain gzip), so the tool's scope is unambiguous. It also hints at a differentiator from shell-based siblings by noting it works 'in process' with 'no zip/tar binary needed', though it never names an alternative tool 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 only implied through the action list and a few conditional phrases ('create takes a directory or a file list', 'extract refuses paths that escape the destination'). There is no explicit statement of when to reach for this tool versus shell_exec/shell_bulk, nor any when-not guidance or prerequisites.

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

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

No annotations exist, so the description carries the full behavioral burden. It implies a read-only inspection tool and mentions a byte cap via parameter, but says nothing about permissions, whether output is truncated/ordered, or the cost of tree-wide todos/stats scans. It adds some value but leaves meaningful behavioral gaps for a 7-parameter tool.

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

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

A single sentence, front-loaded with the domain and then broken into four clearly labeled action clauses. Every clause earns its place by explaining what a distinct action returns, with no filler.

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

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

With no output schema, the description usefully summarizes each action's return shape (functions/classes/types with line numbers, dependencies, markers, LOC by language), which is what an agent needs to pick an action. It omits output ordering, truncation behavior, and how limit/max_bytes interact with results, so it is strong but not exhaustive.

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

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

Schema description coverage is 100%, so the schema already documents path, glob, tags, limit, max_bytes and max_depth. The description only restates the per-action applicability (outline/imports vs todos/stats) that the schema itself already encodes, adding no new parameter meaning. Baseline 3 applies.

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

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

The description names a specific domain (structural views of source code) and enumerates the four actions with their return content, so an agent can tell it apart from file_read or search_text. It stops short of naming a sibling explicitly or summarizing a single unifying verb beyond 'views', which keeps it out of the top band.

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 an explicit usage rule for one action ('read this before reading the file' for outline) and each action's parameter descriptions state the applicable scope (path is a file for outline/imports, a directory for todos/stats). There is no guidance on when to prefer search_text or fs_list over this tool, so it falls short of 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It adds a valuable trait for apply—context-based hunk matching so patches survive shifted lines—but omits mutation/permission details, and does not mention dry_run or what the tool returns.

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, front-loaded with the core purpose, followed by parenthetical mode definitions. Every clause contributes information, though bullets would be slightly easier to parse.

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

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

For a 10-parameter tool with three modes and no output schema, the description covers mode selection and a key apply behavior. However, it does not describe return values, dry_run semantics, or error handling, leaving gaps that the missing output schema cannot fill.

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

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

Schema description coverage is 100%, so the parameter meanings are already documented. The description adds action-to-parameter grouping (files uses path/to, text uses a/b, apply uses path/patch), but no syntax or format details beyond the schema; baseline 3 is appropriate.

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

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

The description states a specific verb and resource (compare/patch text) and enumerates the three modes: files, text, apply. Each mode is defined concisely, so an agent can immediately tell this tool apart from file_edit or search_text 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?

It gives clear context for when to use each action: files for two file paths, text for inline strings, apply for a unified diff. There are no exclusions or explicit alternatives (e.g., use file_edit instead), but the mode descriptions provide strong 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?

With no annotations, the description carries the full burden. It usefully flags that jwt_decode does NOT verify the signature and mentions a max_bytes cap on output, which are real behavioral facts. It omits error behavior, file-size limits for path reads, and whether random output is cryptographically secure.

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 capability sentence is front-loaded with the operation list, followed by a short input-source sentence. No filler, though the enumeration is long and could be tabular.

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?

No output schema exists, yet the description conveys enough for a multi-action converter: the action set, input source, and the key cryptographic caveat. It is close to complete; return-value specifics per action remain implicit.

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

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

Schema coverage is 100%, so baseline is 3. The description's parentheticals (hash algorithms, jwt header/payload, input from text or file) largely restate what the schema fields already document, adding little beyond the schema.

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

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

The description names the exact operation set (base64/hex/url/html encode-decode, hash, uuid, random, jwt_decode, timestamp) matching the enum verbatim, so an agent knows precisely what it does. It is scoped as 'small conversions', but does not explicitly differentiate itself from siblings like shell_exec or json_tool.

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 enumerated action list and the 'Reads inline text or a file' input note, and 'Small conversions' bounds the intended scope. However, there is no explicit when-to-use-vs-alternatives guidance (e.g., vs shell_exec), leaving routing 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 carries the full burden and does well: it discloses the reference-frame rule (line numbers are against the ORIGINAL file), a hard constraint (line ranges must not overlap), failure semantics (replace_text fails unless it matches expect_count, default 1), and a safe preview path via dry_run. Missing are permission/backup behavior and what the dry_run output actually looks like, so not 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 dense sentences, each front-loaded with high-value constraints: batching first, then op list, then the line-number/overlap rule, then failure and preview semantics. No filler and no repetition of the 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 multi-op mutation tool with no output schema and no annotations, the description covers the operation model, ordering constraints, failure conditions, and preview path — enough to call it correctly. It leaves the return value of a write/dry_run unexplained and does not address concurrent-edit or stale-file handling beyond expect_match's mention in the schema.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning beyond the schema: the non-overlap constraint and original-file line numbering for start_line/end_line, expect_count's default of 1 and all=true override for replace_text, and dry_run's diff-preview behavior. It doesn't explain eol or expect_match/allow_no_match, which the schema covers.

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 with scope ('Patch parts of a file — several edits in ONE call') and enumerates the op types, which makes it unmistakably the incremental-edit tool rather than file_write. It does not explicitly name a sibling or draw the boundary against file_write, 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?

Gives real usage context: plan all edits from a single file_read because line numbers refer to the original file, and preview with dry_run=true. It also distinguishes replace_text (with expect_count/all) from the line-based ops. There is no explicit 'when not to use' or named alternative (e.g. use file_write for a full rewrite), so it is clear but not exhaustive.

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 burden. It usefully discloses output shape (line-numbered, middle-truncated at max_output_bytes) and negative-index semantics, which is real behavioral context. It says nothing about error behavior for missing files, permissions, or how conflicting modes (e.g. start_line vs head_lines) resolve.

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

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

One dense, front-loaded sentence with the primary capability ('Read a file') first and the qualifiers following. It is information-rich with no filler, though the em-dash chain makes it slightly harder to scan than a short bulleted breakdown would be.

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 14-parameter tool with no annotations and no output schema, the description covers the headline modes and truncation behavior adequately. It stops short of explaining error handling, parameter conflicts, or binary/base64 handling, leaving some gaps that the schema only partially fills.

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

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

With 100% schema description coverage, the schema already documents all 14 parameters including defaults and enums; baseline is 3. The description reinforces the most important ones (start_line/end_line negatives, head_lines/tail_lines, match regex) but adds no syntax or precedence detail beyond the schema.

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

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

States a specific verb+resource ('Read a file') and immediately enumerates the access modes (line range, head/tail, regex match), so an agent knows exactly what capability it offers. The 'middle-truncated at max_output_bytes' and 'line-numbered' phrasing further pins down the behavior in a way that distinguishes it from raw shell reads.

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

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

It gives a clear usage rationale ('far cheaper than reading a whole file') that steers the agent toward partial reads rather than whole-file reads. However, it never names the sibling tools (search_text, search_files) or states when those should be preferred over match= mode, so no explicit exclusions are provided.

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

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

With no annotations, the description carries the full burden. It usefully discloses side effects: parent directories are created and existing EOL style is preserved, and create_new fails on existing files. However, it never states that the default 'overwrite' destroys existing content irreversibly, nor anything about permissions or failure behavior for the other modes.

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 action first and the alternative-tool routing last. Every clause carries 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 7-param mutation tool with no annotations and no output schema, the description covers the destructive default, the mode failure case, and side effects like directory creation and EOL preservation. The main remaining gap is not flagging the data-loss risk of the default overwrite mode.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: the per-mode behavior of overwrite/append/prepend and the failure condition for create_new, which the enum only labels 'Default overwrite'. Other params (eol, encoding, create_dirs) are left entirely to the schema.

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

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

States a specific verb ('Write a whole file') with explicit scope ('whole', as opposed to partial edits), and names the sibling it is not by routing to file_edit. An agent can distinguish it from file_edit or shell-based writes without opening any 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?

Explicitly routes the agent: 'For a small change to a big file use file_edit.' It also documents the discriminating condition for create_new ('fails if it exists'). No guidance on when-not to use it versus shell_bulk or other write paths, but the primary alternative is covered.

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 non-obvious default behavior: recursion to depth, glob filtering, and default skipping of .git/node_modules/dist. However, it does not describe permissions, error behavior, or the fact that output is middle-truncated (that detail lives only in the schema), and 'and friends' is vague about the actual skip list.

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 with the primary action front-loaded and the modifier behaviors trailing. No filler, though 'and friends' sacrifices precision for brevity.

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

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

For an 8-parameter read tool with no annotations and no output schema, the description covers the core behaviors but never explains the shape of what is returned or the truncation semantics. Adequate, not complete.

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

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

Schema description coverage is 100%, so every parameter is already documented, setting the baseline at 3. The description echoes depth and pattern and adds the default skip behavior, but contributes no additional syntax or constraint detail beyond the schema.

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

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

States a specific verb+resource ('List a directory') and extends it to the stat case ('or stat one path'), which an agent can act on immediately. It does not explicitly contrast itself with overlapping siblings like search_files or file_read, 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?

There is no when-to-use guidance and no mention of alternatives, despite siblings such as search_files, file_read, and shell_exec plausibly covering some of the same ground. The only routing-ish information is implicit in the behavior sentence.

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 of behavioral disclosure. It adds one specific rule (delete refuses a non-empty directory unless recursive=true) and a vague 'recursive where it makes sense,' but omits critical context: whether delete is permanent, what happens on overwrite (force), permission requirements, error modes, and return formats. For a tool performing destructive operations, this is a significant 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 description is a single, front-loaded paragraph that efficiently packs scope, action list, and one behavioral note. It avoids redundancy and is appropriately sized for a 13-parameter tool, though minor structural improvements (e.g., separating the behavioral note) could enhance scannability.

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

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

Given the tool's complexity (12 actions, 13 parameters, no output schema, no annotations), the description adequately covers selection by stating scope and exclusions, and the schema covers parameter invocation. However, it lacks detail on what each action returns or how errors surface — gaps that could mislead an agent about output expectations.

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

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

Schema description coverage is 100%, so each parameter is fully documented in the schema. The description restates the list of actions and hash algorithms, which duplicates the enum values with no added syntax or format detail. Per the rubric, a baseline of 3 is appropriate when the schema does the heavy lifting.

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 resource (filesystem) and enumerates all supported operations, with an explicit exclusion: 'other than reading/writing content.' This immediately distinguishes it from siblings like file_read and file_write, giving an agent a precise sense of what the tool does and does not cover.

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 exclusion of reading/writing content implies that file_read and file_write should be used for those tasks, but no explicit when-to-use guidance or named alternatives are provided. The delete condition (needs recursive=true for non-empty dirs) is a behavioral rule, not usage routing. Overall, 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses the token-cheap output preference, that git runs directly without a shell, and that quoting/newlines need no escaping — all non-obvious execution-model facts. It stops short of warning about destructive write actions (force push, reset --hard, clean) or auth needs for fetch/pull/push, so it is not exhaustive.

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 deliberately compressed: the main behavior and routing rule are front-loaded, action lists are comma-dense, and the closing escaping note is one clause. No sentence is filler.

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

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

For an 18-parameter mutation-capable tool with no output schema and no annotations, the description covers action coverage and execution semantics well. It could do more on destructive-operation consequences and output shape, but the schema's explicit warnings (e.g. hard: 'DISCARDS working tree changes') fill part of that 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 100%, so the schema already documents all 18 parameters including enum values and per-action flags; the baseline of 3 applies. The description reinforces the raw-action pattern and the no-escape rule for messages, but adds little parameter meaning the schema does not already provide.

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 ('Run git') with an explicit quality goal ('compact, token-cheap output'), then enumerates the read and write action families so the agent immediately knows the tool's surface. It is trivially distinguishable from shell_exec because it is git-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?

The description partitions the supported actions into Read and Write lists and gives a clear fallback ('Anything else: action="raw" with args'), which tells the agent exactly when to use which mode. It does not, however, say when to prefer this over the sibling shell_exec/shell_exec_async tools, which is the main remaining gap.

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 load and does disclose genuinely non-obvious behavior: JSON bodies are pretty-printed, large bodies are truncated, and json= sets Content-Type. It omits error-surface behavior, auth/credential handling, and side effects of the `assign` variable write.

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

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

Two sentences, front-loaded with the core capability and outcome, then the body-mode distinction. No filler and nothing repeated.

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-parameter, no-output-schema tool with no annotations, the description covers purpose, return shape and body semantics; the per-parameter detail is fully carried by the schema. It would be complete if it mentioned the variable-storage side effect and TLS/redirect caveats at a high level, but nothing critical is missing.

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

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

Schema description coverage is 100%, so all 13 parameters are already documented in the schema; baseline is 3. The description only re-frames the json-vs-body choice, which the schema already covers, and adds no syntax or format detail beyond it.

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 (make an HTTP(S) request) plus exactly what it reports (status, timing, headers, body) and its intended context. It does not distinguish itself from the sibling `net`, which is the only remaining ambiguity for an agent choosing between 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?

"for testing the API you are building or calling" gives a clear usage context, and the json=/body= sentence steers the two main body modes. It stops short of stating when NOT to use it (e.g. versus shell_exec + curl) or naming 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?

No annotations are supplied, so the description carries the burden, and it does useful work: 'without rewriting the whole file' discloses the partial-mutation behavior, and 'Nothing is written in this mode' clearly marks the content= mode as non-destructive. It omits auth/permission needs, error behavior on missing paths, and write scope beyond 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?

One dense paragraph with the core value proposition ('without rewriting the whole file') front-loaded, followed by the action list, path syntax, and mode selection. Every clause earns its place, though the action enumeration and examples make it slightly list-heavy.

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

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

For an 8-parameter, 7-action tool with no annotations and no output schema, the description covers actions, path syntax, and file-vs-inline modes well. It does not describe return values or per-action error semantics, which is a modest gap given there is no output schema.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by giving concrete path syntax ('scripts.build', 'items[0].name') and clarifying that content= is inline and produces no writes. It still leaves the value/create_missing/max_bytes semantics to the schema.

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

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

The description names a specific verb+resource and enumerates every action (get, set, delete, merge, keys, validate, format) so the agent knows exactly what the tool covers. It also distinguishes itself from generic file siblings with 'without rewriting the whole file', signaling a JSON-aware partial-patch tool rather than file_read/file_write/file_edit.

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

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

It clearly states the two operating modes ('Works on a file (path=) or inline text (content=)'), which tells the agent when to supply which parameter. It does not explicitly say when to prefer this over file_edit or file_read, so it stops short of full routing 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 behavioral burden. It does disclose some traits the schema does not: tcp_check reports timing, listening identifies the owning pid, and ping is packet-based. It omits what happens on failure, whether elevated privileges are needed for port/pid enumeration, and the default timeouts and byte caps that the schema only names.

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 front-loads the tool's identity ('Network probes') and then itemizes each action with its defining detail. No filler, no restatement of the name, and every clause adds distinguishing 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 an eight-parameter, no-annotation, no-output-schema tool, the description covers what each action does but says nothing about return shape, error behavior, or privilege requirements for the more sensitive probes (listening, interfaces). It is adequate but leaves gaps an agent would need to discover by trial.

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

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

Schema description coverage is 100% and all eight parameters are documented there, including which action each one belongs to, so the description need not repeat them. The description adds nothing about parameter interaction beyond what the schema already states, which is the baseline for a fully covered schema.

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

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

The description enumerates five concrete probes (dns, tcp_check, listening, interfaces, ping) and states what each one returns, so the agent knows exactly what the tool does. It does not, however, differentiate itself from siblings like http_request or shell_exec, which could also answer some of these questions.

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?

Enumerating the five actions with their meaning implies when each sub-action applies, which is useful selection guidance. But there is no explicit 'use this instead of X' routing against siblings (http_request, shell_exec, sys_info), and no stated prerequisites such as privileges for the listening 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 full burden, and it does disclose the detection mechanism (lockfile reads). However it never distinguishes read-only actions (detect/scripts/list/outdated) from mutating ones (install/add/remove), nor warns about long install durations, required permissions, or network access needed by the underlying managers.

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 core value proposition, then the action list, then the detection detail—logical and mostly waste-free. The 15-manager enumeration is long but earns its place by scoping applicability; overall appropriately sized.

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 9-parameter tool with no annotations and no output schema, the description covers actions and detection well but omits return format, output truncation behavior (max_bytes), timeouts, and mutation semantics. Adequate but with visible gaps for such a broad tool.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the action enum and per-action parameters. The description's action list adds minor mapping value (run a script, list scripts, detect) but does not go beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb+resource (drive a package manager) and enumerates the exact managers and actions supported, so an agent immediately knows this wraps npm/pnpm/cargo/etc. rather than being another generic shell runner. It is clearly distinguishable from siblings like shell_exec or proc.

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 the key selection condition: detection reads lockfiles so it picks the manager the repo actually uses, and manager can be forced. It gives clear context for when to reach for this over a raw shell tool, but offers no explicit when-not guidance or edge cases (e.g., no lockfile present).

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 add real value: the confirm=true guardrail for killing by name, the destructive kill semantics, and the cross-platform implementation (ps on Unix vs PowerShell/tasklist on Windows). It omits permissions required, reversibility, and output characteristics for a tool that can terminate processes, so it is not fully transparent.

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 dense sentence that is front-loaded with the resource and organized as labeled per-action clauses, so nothing is wasted. The heavy parenthetical nesting and run-on length keep it from being maximally scannable, but it is efficient.

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 9-parameter, multi-action, destructive-capable tool with no annotations and no output schema, the description covers the action surface and cross-platform behavior but leaves gaps: no return/output shape is described (only a max_bytes hint exists in schema) and no safety or permission caveats beyond confirm=true. Adequate but not complete for the complexity.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema and the baseline is 3. The description largely restates schema content (filter by name, sort by cpu/memory, kill by pid) rather than adding syntax or edge-case meaning beyond what the schema provides.

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

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

The description names the resource (processes on this machine) and enumerates four distinct operations (list/tree/info/kill) with what each does, so an agent immediately knows this is a process-inspection/control tool rather than general shell execution. It does not explicitly name any sibling to rule out (e.g., shell_exec), so it stops short of full sibling differentiation.

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

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

Usage is implied through the action-by-action breakdown (filter by name, sort by cpu/memory, kill by pid or name), which gives an agent enough to select the right action. However, there is no explicit when-to-use vs. when-not guidance and no alternative named (e.g., sys_info for machine stats or shell_exec for arbitrary commands), leaving the routing 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 carries the full disclosure burden, and it does reasonably well: it enumerates the returned fields (git dirty state, entry points, build/test/lint commands, config files) and notes the cost advantage of a single aggregated call. It does not explicitly state that the operation is read-only/side-effect free, nor anything about the effect of the max_bytes cap on truncation.

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 scoping statement is front-loaded, and the enumeration is dense but every clause earns its place by telling the agent what it will get back. The closing comparative sentence justifies the single-call design in six words.

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

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

There is no output schema, so the description must describe return contents, and it does so thoroughly enough for an agent to decide and call correctly. Combined with the fully documented input schema and self-evident read-only nature, nothing critical is missing.

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

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

Schema description coverage is 100%, so all four parameters (cwd, deps, max_bytes, max_files) are already documented in the schema. The description adds no additional meaning about any parameter, so baseline 3 applies.

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

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

The description names a specific action ('orient yourself in an unfamiliar repository') and exhaustively enumerates the resource it returns: languages, package manager, dependencies, frameworks, scripts, entry points, commands, git state, config files. That content list makes it clearly distinguishable in practice from fs_list, search_files, or git, though 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?

It states a clear use context ('unfamiliar repository', 'ONE call') and contrasts with the alternative approach ('cheaper than exploring the tree by hand'). However it never names a sibling tool or states when not to use it (e.g. when you only need one targeted file read), so no 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?

With no annotations, the description carries the full burden; it usefully discloses cross-platform consistent output and default sort direction, which goes beyond the bare name. However, it never confirms this is a read-only/non-mutating operation, nor mentions traversal safety, performance, or output shape for a 17-param tool.

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

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

A single tight sentence with zero filler that front-loads the verb and resource before the differentiator and sort options. Nothing is 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?

For a 17-parameter tool with no annotations and no output schema, the description is thin — it says nothing about return values or how the many filtering parameters interact. The rich schema compensates somewhat, but the description stops at minimum viability.

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

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

Schema description coverage is 100%, so the schema fully documents all 17 parameters, making the baseline 3 appropriate. The description's mention of sorting by path/size/mtime merely restates what the schema already provides and adds no new parameter meaning.

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

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

States a specific verb (Find) and resource (files and directories) with the full dimension set (name glob, size, age, type). The phrase 'the find you would otherwise shell out for' implicitly distinguishes it from shell_exec/shell_bulk, while the file-oriented framing separates it from the content-oriented search_text sibling.

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

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

The 'instead of shelling out for find' line implies usage but never states explicit when-to-use vs the shell_* or search_text siblings. No exclusions, prerequisites, or decision criteria are given, so routing relies on 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 carries the full burden and does well: it discloses the default exclusions (.git/node_modules/build, binaries), .gitignore honouring, and — critically — that replace rewrites files on disk while dry_run only shows a diff. It stops short of stating permission requirements or interaction with respect_gitignore/skip_dirs overrides.

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

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

Three dense sentences, zero filler, and the core capability plus the two most decision-relevant modes are front-loaded before the riskier replace/dry_run note.

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 21-parameter tool with no output schema, the description supplies the essentials an agent needs: what it searches, what it skips, what the output contains, and the one dangerous mode. It is reasonably complete, though it could say more about the interaction between user-supplied skip_dirs/glob/exclude and the built-in defaults.

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

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

Schema description coverage is 100%, so the schema already documents all 21 parameters thoroughly. The description restates a handful of them (files_only, count_only, replace, dry_run) in workflow terms, which is modest added value, but most parameter meaning lives in the schema and the description adds no syntax or default detail beyond it.

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 ("Grep a whole tree") and describes the output shape ("matching lines with file:line and optional context"), which is concrete and unambiguous. It never differentiates itself from the sibling search_files, so an agent must still infer the routing between the two.

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 mode-selection guidance: "Use files_only=true to just locate files, count_only=true for tallies" and the replace/dry_run workflow. This covers when to pick each mode, but offers no guidance on when to prefer this tool over siblings like search_files or shell_exec, and no 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 meaningful behavior: in-order sequential execution, per-step retry/condition/failure handling, cross-step state reading (prev.*, steps[i], vars.<name>, failed_count), and token-cost tradeoffs via capture. It omits the risky part of the picture: no warning about destructive side effects, no statement of permissions or sandboxing, and no hint about the shape of what comes back. Adequate but incomplete for a shell-execution 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?

Four sentences, front-loaded with the core purpose and then the step capabilities and expression namespaces. Dense but readable, with no filler prose. The middle list partially mirrors schema fields, which is slight redundancy, but it earns its place by framing the features before the agent opens the nested 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 10-parameter tool with nested step objects, no output schema and no annotations, the description covers the essential mental model: batching, ordering, per-step conditions, retries, failure policy, variable assignment, and output capture. What is missing is the return structure of a run and explicit positioning against the other shell siblings, but the condition namespaces (prev.ok, failed_count) hint at the result shape.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds value beyond the schema: it enumerates the readable namespaces for conditions and ${...} interpolation (prev.ok, prev.exit, prev.stdout, step.<id>.ok, steps[0].exit, vars.<name>, failed_count), which the schema only gestures at with an example. It also paraphrases assign and capture succinctly, so an agent can grasp the semantics without reading every nested property.

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 with a distinguishing scope: 'Run MANY commands in one call, in order', which implicitly separates it from the single-command siblings like shell_exec. It also tags the value proposition ('token-efficient way to work'). It stops short of naming an alternative tool outright, so the differentiation is inferred 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 description gives one concrete usage preference ('Prefer capture="on_failure" for long pipelines') with the reason why (silent on success, full output where it broke). However, it never says when to choose shell_bulk over shell_exec or shell_exec_async, nor when sequential batching is inappropriate. Usage is implied by the batching framing rather than asserted.

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 disclose meaningful traits: 'Full system access' signals the elevated privilege/risk, and it names the exact return surface (exit code, stdout, stderr) plus the blocking wait. It omits auth/permission requirements and side-effect warnings, so not 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 tight sentences with the core action, return values, privilege scope, and usage condition all front-loaded. No filler or repetition.

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

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

For an 11-param, mutation-capable tool with no output schema, the description supplies the missing return-value semantics (exit code/stdout/stderr) and the privilege level, while the rich schema covers parameters. It stops short of only because destructive/irreversibility guidance is absent.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail. The description adds only 'or the one you name' for the shell override and the return-value surface; it contributes little semantic detail beyond the schema, which is the correct baseline 3.

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

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

States a specific verb+resource ('Run a shell command') and scopes it behaviorally with 'wait for it to finish' and 'short-lived', which implicitly separates it from shell_exec_async. It never names the async sibling outright, so it falls just short of full sibling differentiation.

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

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

'Use for anything short-lived' gives clear positive guidance and, combined with 'wait for it to finish', implies that long-running work belongs elsewhere (shell_exec_async/shell_job). No explicit exclusion or named alternative, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does disclose key behavior: non-blocking start, immediate job_id return, and lifecycle management via shell_job. It doesn't cover output capture/buffering, resource cleanup, or permission needs, leaving some 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?

Three tight sentences, front-loading the core behavior, then use cases, then the follow-up tool. Every sentence earns its place with zero 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?

No output schema exists, and the description does explain the key return value (job_id) and how to interact with it later via shell_job. Covers the essentials for an 8-param tool; only minor gaps remain around output handling and cleanup.

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

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

Schema description coverage is 100% – cwd, env, name, login, shell, timeout_ms, and interactive are all documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a precise verb+resource+behavior ('Start a command in the background and return a job_id immediately'), which clearly distinguishes it from the foreground shell_exec and pairs it with shell_job. An agent knows exactly what this does 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?

Gives concrete use cases ('long builds, dev servers, watchers and tailing logs') and names the companion tool shell_job for reading/stopping the job. It does not explicitly state when NOT to use it (e.g., use shell_exec for short/blocking commands), but the async framing implies it.

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

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

No annotations are provided, so the description carries the full burden. 'Report' plus 'call this once' implies a safe, idempotent read with no side effects, and it discloses that guardrails and effective config are included. It does not explicitly confirm read-only/no-mutation behavior, nor describe the output shape, so the behavioral picture is only partially filled in.

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 scope enumeration and closed with the actionable usage cue. No filler, no restatement of the tool name.

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

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

With no output schema, the description must convey what comes back, and listing the reported categories (platform, cwd, shell, config, guardrails) does that reasonably well. It could be slightly more explicit about return structure, but an agent has enough to decide to call it.

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 beyond what the schema already shows; the baseline of 4 applies. The description correctly does not invent parameter guidance.

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

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

States a specific verb ('Report') and resource ('the environment') and enumerates exactly what is covered: platform, server cwd, active shell, installed shells, effective config, guardrails. It is clearly an inspection tool, though it never explicitly differentiates itself from the nearby sys_info or project_info 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?

"Call this once at the start if you need to know what you are driving" gives a clear when-to-use condition and a frequency constraint ('once'). It stops short of naming alternatives (sys_info, vars) that an agent might choose instead for overlapping information.

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 usefully discloses that output/wait can block up to wait_ms and that offset supports incremental streaming via next_offset. It does not discuss permissions, side effects of kill/remove, or default behavior beyond what the schema already states, but the key blocking and streaming behaviors are surfaced.

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: purpose and action list first, then blocking behavior, then offset streaming. Every sentence adds useful information with no repetition or filler.

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

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

For an eight-parameter control tool with no output schema, the description covers the core mental model and the critical streaming protocol. It leaves some return-value and destructive-action context to the schema, but it is complete enough to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics for offset and wait_ms by explaining how next_offset enables streaming without re-reading. It does not explain every parameter, but it improves the most important ones beyond the schema.

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

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

The description states a specific verb and resource: 'Inspect and control background jobs.' It enumerates all seven actions, making clear that this is the job-management tool rather than an execution tool like shell_exec or shell_exec_async.

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 clear context for using output and wait, including that blocking up to wait_ms replaces a polling loop and that next_offset should be reused as offset. It does not explicitly name alternatives such as shell_exec_async or state when not to use this tool, so it stops short of full routing 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 behavioral burden. It does disclose "Read-only" and clarifies scope for disk (free space per mount) and network (interfaces), but says nothing about output truncation despite max_bytes, nor about whether env output can expose sensitive values.

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

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

A single sentence front-loads the resource, then enumerates modes compactly, closing with the safety trait. 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?

There is no output schema, so describing what each action returns (free space per mount, interfaces, env variables) is the right move and it is done adequately. Minor gaps: no truncation behavior for max_bytes and the omitted "all" mode.

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

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

Schema description coverage is 100%, so the baseline is 3. The description glosses the enum values (memory, disk, network, env) with short parentheticals, which adds marginal meaning, but filter/show_values/max_bytes semantics live entirely in the schema and the "all" action is never mentioned.

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 resource (machine facts) and enumerates the specific fact categories it returns, so an agent knows exactly what it will get. It does not differentiate itself from plausible siblings such as proc or shell_info, leaving the boundary 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?

"overview (default)" implies the common usage path and "Read-only" frames the operation, which is useful implied guidance. There is no explicit when-to-use/when-not guidance and no mention of when a sibling like proc would be preferable.

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, and it does well: it discloses that list shows names/types/sizes but not full values, that secret:true values remain usable via ${vars.…} while never being echoed, and that clear drops every variable. It omits permission/auth requirements and error behavior, keeping it short of 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 sentences, front-loaded with the core concept and followed by reference syntax and behavioral notes. The middle list of contexts is long but each item is informative; little is wasted, though it could be tightened.

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 9-action, 13-parameter tool with no output schema, the description covers the crucial cross-cutting behaviors (persistence, reference syntax, secret handling, list redaction) that an agent cannot infer from the schema. The per-action semantics rest on the 100%-covered schema, so the combination is nearly complete; only auth/permission context is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine semantics beyond the schema: the ${vars.<name>} expansion syntax, that a set value string is itself ${...}-expanded for composition, and the secret/reveal trade-off. These enrich interpretation rather than merely restating parameter names.

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 resource (server-side variables that persist between calls) and its core value proposition (store once, reference via ${vars.<name>}). It conveys the multi-action nature by naming list, secret marking, and the writing tools, though it never frames itself explicitly as an action-dispatched store, so an agent must open the schema to grasp the full action set.

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

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

It gives a clear when-to-use rationale ('so a value never has to be re-sent through the conversation') and enumerates the contexts where references work (command, cwd, env, path, URL, header, git message, bulk step). It also clarifies that secret values are excluded from list output, but gives no explicit when-not-to-use or disambiguation against sibling read/write tools.

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

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

With no annotations, the description carries the full burden and does well: it discloses that start returns a watch_id, that poll blocks up to wait_ms, and that events are coalesced per path so a triple-save is reported once. It omits error/failure behavior and permission requirements, so it's strong but not complete.

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

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

Three dense sentences with no waste, front-loaded with the tool's purpose before the action semantics. Every clause (watch_id return, poll blocking, coalescing) earns its place.

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

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

For a 10-parameter, multi-action tool with no annotations and no output schema, the description covers the action lifecycle and key behaviors adequately. It doesn't describe the shape of returned events, but it covers enough for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters with per-action notes and defaults. The description adds only the coalescing and blocking semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Watch a file or directory for changes') and enumerates the four sub-actions, so the tool's scope is unmistakable. It doesn't explicitly contrast itself with siblings like fs_list or search_files, which keeps it short of a 5.

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

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

It tells the agent how to use poll effectively ('one call replaces a polling loop') and what each action does, which is genuine usage guidance. However, there is no explicit when-to-use-this-vs-alternatives or when-not, so it stays at implied usage.

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