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

The annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavior: cache invalidation on write/new directory, the output discriminator (directory_created vs file_written), and that it is not batch-safe. It does not say what happens when mode is omitted or that overwrite destroys prior contents beyond a passing hint, so it stops 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?

Labelled one-line sections (Use when / Avoid when / Speed / Output / Batch-safe) put the decision-relevant information first with almost no filler. Minor dead weight: 'kept in sync with the Venira native app tool' consumes space without changing agent behavior.

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

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

With six parameters, low schema coverage and no output schema, the description does supply the output shape and the cache-invalidation side effect. It still leaves an agent guessing about create_dirs, the default mode, and the purpose of expected_sha256, which are material for calling 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 description coverage is only 17%, so the description must carry the load, and it explains kind, content and mode=overwrite plus the implicit mode=create/append distinction. However, it never mentions create_dirs (does the parent path get made?) or expected_sha256 (an optimistic-concurrency guard), which are two of the six parameters and easily misused.

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

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

The description names a specific verb (Create) and both resources (directory or file), and explicitly states it merges project_create_directory plus the new-file case of project_write_file. An agent can distinguish this tool from project_create_directory and project_write_file 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?

Explicit 'Use when' names both branches (kind=directory; kind=file with content+mode) and 'Avoid when' routes existing-file edits to project_edit_file and preservation-sensitive overwrites to project_write_file mode=overwrite. Both the positive and negative cases name the sibling tool that handles them.

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 non-readonly, idempotent, non-destructive, closed-world. The description adds context annotations cannot express: the create_parents default, the return shape ('directory_created: relative_path'), and 'Batch-safe: no', which warns against parallel invocations. It omits what happens on an already-existing directory (error vs. silent success), 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?

Labeled lines (Use when / Avoid when / Output / Batch-safe) front-load the essential facts with no filler sentences. The 'Speed: nhanh' line is an untranslated token that carries little actionable meaning and slightly dilutes the otherwise tight structure.

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

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

For a two-parameter, non-destructive creation tool with rich annotations and no output schema, the description covers purpose, preconditions, return value, and concurrency safety. Only the existing-directory error behavior and full create_parents semantics are left 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 50%: relative_path is documented in the schema, but create_parents has no schema description. The description compensates only partially by stating its default value, without explaining the consequence of setting it false (e.g., failure when the parent is missing).

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 ('Create a directory') and immediately surfaces the create_parents default. It implicitly distinguishes itself from project_write_file by noting the create_dirs=true alternative, though it does not name the sibling 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?

Explicit 'Use when' and 'Avoid when' clauses give the agent both the positive precondition (directory must exist before writing into a new path) and two exclusion conditions, one of which points at an alternative approach (write_file with create_dirs=true).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description still adds value by stating the operation is not undoable, that it clears the read/list/search cache, and that it is not batch-safe. It stops short of describing error behavior (missing path, recursive flag misuse on a file), which matters for a destructive 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?

Front-loaded with the action, then structured labeled lines for usage, avoidance, speed, output, and batch safety. Every line carries distinct information with no repetition of schema or annotations.

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?

Covers the destructive/irreversible nature, the cache side effect, and the return shape despite there being no output schema, which is exactly what an agent needs. Missing only details about failure paths (nonexistent path, permission errors) since no error schema exists.

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 only 50% — relative_path is documented in the schema but recursive has no description there. The description compensates by explaining recursive only in the context of directories, though it doesn't state the default or what happens if omitted on a directory.

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 (Delete) and resource (file or directory) and immediately qualifies the directory case with recursive=true. It is clearly distinguishable from siblings such as project_write_file, project_edit_file, and project_create_directory.

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

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

Uses explicit 'Use when' and 'Avoid when' clauses and names the alternative operations (write/edit) that should be chosen instead. The condition for selecting this tool is unambiguous.

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

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

Annotations already declare mutation, non-idempotent, non-destructive status, so the description's job is to add non-obvious traits — it does: cache invalidation for the affected path, speed profile, non-batch-safety, and the returned file_written/sha256_before-after fields. Missing only an explicit statement of failure behavior when old_text isn't found, 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?

Labeled clauses (Use when / Avoid when / Speed / Output / Batch-safe) front-load the core mechanism and route quickly. Efficient, though the telegraphic 'Batch-safe: no' phrasing is slightly cryptic versus prose.

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, but the description names the return fields so the agent knows what comes back, and it covers caching side effects and the primary param meanings. Reasonably complete for a 6-param mutation tool, with the replace_all gap the main omission.

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 only 17%, so the description must compensate; it explains expected_sha256's purpose ('guard against blind overwrites') and the edits[] vs single-pair relationship, which is genuinely useful. However replace_all and the multi-section maxItems:64 limit are never explained, leaving key semantics undocumented.

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

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

States a specific verb and resource ('Edit a file by exact text replacement') plus the two supported mechanisms (single old_text/new_text pair or edits[] batch). It explicitly contrasts with project_write_file, so the agent can pick this tool over its closest sibling without reading either 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?

Explicit 'Use when' (one or a few known text sections, pair with expected_sha256) and 'Avoid when' (whole-file rewrite -> project_write_file; haven't read the file for old_text). Alternatives and exclusions are named directly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds real context beyond that: performance characteristics ('very fast'), cache semantics ('cache validated by mtime+size'), and concurrency posture ('Batch-safe: yes'). The stated output field names also set expectations. It does not mention error behavior for missing paths, which keeps it at 4 rather than 5.

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

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

Front-loaded with the core purpose, then organized into labeled lines (Use when / Avoid when / Speed / Output / Batch-safe) that are each one short clause. Every line carries actionable information 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?

For a one-parameter read tool with no output schema, the description covers purpose, when to use, an alternative, performance, output shape, and batch safety — everything an agent needs to call it correctly and interpret the result.

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 is a single parameter with 100% schema description coverage, so the schema already fully documents its type and the workspace-relative/absolute semantics. The description adds no syntax or constraint detail beyond what the schema supplies, 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 the resource and exactly what is returned (kind, size, modification time) for files or directories, and explicitly separates it from project_read_file, which is the nearest sibling an agent could confuse it with.

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 'Use when' (only need size/mtime/kind, or checking path existence) and an explicit 'Avoid when' naming the alternative tool (project_read_file) for file contents. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint/openWorldHint; the description goes well beyond them by disclosing cost ('fast, ~a few ms + 1 audit DB query'), the fact that a DB query is performed and how to skip it via include_audit=false, the output key set, and that it is not batch-safe. That is exactly the kind of side-effect/cost context annotations cannot carry.

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?

Labeled lines (Use when / Avoid when / Speed / Output / Batch-safe) front-load the important routing information with no filler. Slight cost from dense jargon and 'Batch-safe: no' reading as a stub, but overall tight.

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 sketches the returned key structure (server, corehost, capability, queue, caches, shells, metrics, audit) and covers speed, exclusion criteria, and the one parameter. Adequate for invocation; it stops short of describing value shapes within those sections, which is acceptable given the tool's diagnostic nature.

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

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

Schema coverage is 0%, so the description must compensate, and it does explain the single parameter's meaning implicitly: include_audit=false skips the audit DB query. It could be slightly sharper by stating the default value, but the trade-off is made clear.

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

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

Names the action (server diagnostics) and enumerates exactly what is inspected: corehost, data dir, audit DB, capability, queue depth, cache hit-rate, running shells, p50/p95 metrics. This is clearly distinguishable from every sibling, which are file/shell/project operations, and an agent can tell it is a read-only diagnostics probe.

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

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

Provides explicit 'Use when' conditions (debugging slowness/errors, verifying backend/DB/audit before reporting, inspecting session cache/metrics) and an explicit 'Avoid when' case (normal file reads/writes). Alternative-oriented guidance is present rather than implied.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description adds real value beyond them: a 1.5s TTL cache that is auto-wiped on write/edit/delete, 'fast' speed, and 'batch-safe: yes'. It stops short of explaining truncation behavior beyond naming a 'truncated' field, and doesn't say what 'hint' contains.

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

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

Front-loaded purpose, then labeled clauses (Use when / Avoid when / Speed / Output / Batch-safe) that an agent can scan in one pass. Zero filler sentences.

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 compensates by naming the return keys (entries, truncated, hint) and summarizing caching and batching behavior. Still incomplete on limit/include_ignored semantics and pagination with a 200-entry cap, which matters for a list 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 coverage is only 25% (only relative_path has a schema description), so the description must compensate. It explains depth's 1..3 tree semantics, which is the most important behavior, but says nothing about limit, include_ignored, or what path resolution means beyond the schema string. Partial compensation for the coverage gap.

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

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

States a specific verb and resource ('List files/directories in the workspace') and immediately contrasts itself with the sibling tools that do adjacent things (project_get_file_info, project_read_file). An agent can distinguish it from all 15 siblings 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?

Explicit 'Use when' clause names three concrete situations (see tree, check a path, list before reading) and an 'Avoid when' clause routes to the two correct alternatives by name. This is the full when/when-not/alternative pattern.

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

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

Annotations only give readOnlyHint and openWorldHint, and the description adds real context: sequential execution, cache reuse for read/info, a response budget, and an ok/error envelope per item. It does not say what happens when one op fails (abort vs. partial success) and 'response budget' stays undefined, which is the main gap for a batch 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?

Front-loaded with the core capability, then labeled sections for usage, speed, and output — highly scannable with no filler sentences. 'Batch-safe: yes' is mildly redundant with readOnlyHint, but overall the text is tight.

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 two parameters at 0% schema coverage and no output schema, the description covers the output envelope shape but leaves the per-operation argument contract and the byte-budget parameter unexplained. Adequate for choosing the tool, incomplete for invoking it correctly on the first try.

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 the load; it names the allowed operation values but never explains the shape of `arguments` for each operation, nor what max_response_bytes_per_item does when exceeded. The 'up to 8' cap and the enum list only restate what the schema already encodes.

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 up to 8 read-only ops in one call) and enumerates the four permitted operations, which cleanly separates it from the single-op siblings like project_read_file and project_search. An agent can pick it 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?

Explicit 'Use when' (2+ files/ops in the same step) and 'Avoid when' (single op, or mutating ops — use the corresponding tool) sections, with the alternative named rather than implied. That is the full when/when-not/alternative triad.

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 readOnlyHint=true and openWorldHint=false, and the description adds useful behavior: truncation via next_start_line, repeat-speed caching validated by mtime+size, and batch-safety. It does not cover error behavior or encoding/binary handling, so it is strong but 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 front-loaded and highly structured with labels for Use when, Avoid when, Speed, Output, and Batch-safe. Every sentence adds useful information without waste.

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

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

With no output schema, the description helpfully lists the output fields and explains truncation and caching. It is nearly complete for a file-read tool, though it leaves several schema parameters under-explained.

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 low at 20%, and the description compensates only partially by explaining 1-based line ranges and next_start_line truncation. It does not clarify max_bytes, line_numbers, or exact inclusive/exclusive semantics for start_line/end_line.

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

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

The description states a specific verb and resource: 'Read a text file,' with optional line-range behavior. It clearly differentiates from siblings by naming project_read_batch and project_get_file_info for adjacent use cases.

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 explicit 'Use when' and 'Avoid when' guidance, naming the sibling alternatives for batch reads and metadata-only needs. The remaining line-range case is also scoped to a single file or one range of a large 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?

Goes beyond the readOnlyHint/openWorldHint annotations by disclosing the range cap, cache reuse ('reuses the per-range read_file cache'), the response shape (text/truncated/next_start_line), and 'Batch-safe: no'. It stops short of covering edge behavior such as overlapping ranges or what happens when start_line exceeds file length, so it is strong but 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?

Compact, front-loaded, and organized into labeled clauses (Use when / Avoid when / Speed / Output / Batch-safe). Each line carries information an agent needs; there is no filler.

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

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

With no output schema, the description usefully summarizes the return shape, and read-only safety is covered by annotations. The remaining gap is parameter-level behavior for the nested range objects and how truncation/next_start_line should be followed, which an agent may still have 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 coverage is 50%: relative_path is documented in-schema, while the nested range fields (start_line, end_line, max_bytes) have no descriptions anywhere. The description adds the 16-range limit and mentions next_start_line in the output, but never explains that end_line/max_bytes are optional or how omitted bounds are treated, so it only partially compensates for the gap.

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

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

States a specific verb and resource ('Read multiple disjoint line ranges of the SAME file in a single call') with the hard cap of 16 ranges baked in. The capitalized SAME file immediately distinguishes it from project_read_batch, which handles different files.

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

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

Explicit 'Use when' (several disjoint segments of one file, e.g. around search hits, avoiding round-trips) and 'Avoid when' clauses that name the correct alternatives by name: project_read_file for whole files and project_read_batch for multiple files. Nothing is left to inference.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses a bounded filesystem walk, hard skip list (node_modules/target/.git), a 2s TTL cache, and scan caps of 4000 files / 300 directories. That is exactly the operational context an agent needs to interpret partial results; the 'Batch-safe: no' tag is terse but informative. It loses a point only for not clarifying what 'truncated' means in practice or how depth affects the scan bound.

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 followed by short labeled lines (Use when / Avoid when / Speed / Output / Batch-safe). Every line carries distinct, actionable information 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?

Even without an output schema, the description gives the return shape (recent_files entries sorted by mtime desc, scanned_files, truncated). Combined with the disclosure of skip rules, caching, and scan caps, an agent has enough to call it correctly and interpret the result. Only the undocumented optional parameters are a mild 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 coverage is only 25% (only relative_path is documented), so the description should compensate more than it does. The skip list and bound hint at include_ignored and depth behavior, but limit's default/max and depth's cost impact are never explained. Partial compensation justifies a middle score rather than a high one.

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

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

States a specific verb and resource ('List files modified most recently in the workspace') plus the scope of the scan and what it skips. It explicitly names the two sibling tools it is not (project_list_files for full listing, project_search for content search), so an agent can distinguish it 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?

Provides explicit 'Use when' (need to know which files just changed, pick next file to read) and 'Avoid when' (full list/by name -> project_list_files, content search -> project_search) clauses. Alternatives and selection conditions are named directly, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description goes further with scan cost ("medium (file scan)"), a 3s TTL cache scoped to identical queries, batch-safety, and the output fields (hits, complete, diagnostics, hint) despite no output schema. It stops short of explaining truncation/limit behavior or whether hits are truncated when `complete` is false, which would matter for correctness.

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 first, then labeled Use when / Avoid / Speed / Output / Batch-safe blocks with zero filler. Every line carries distinct information, and the most decision-relevant content 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?

Good on outputs (pre-empting the missing output schema) and cost, but for a 12-parameter search tool the absence of any guidance on scoping (glob/relative_path), result limiting (limit, count_only), and context_lines leaves the agent likely to call it with defaults that don't match its intent.

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 8% (only relative_path is documented), so the description carries the burden for 12 parameters but only adds meaning to `query`, `kind`, and `regex`. Filters like glob, exclude_glob, whole_word, case_sensitive, include_hidden, context_lines, count_only, and limit are named nowhere, leaving the agent unaware they exist.

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 plus the four exact search modes (file name, directory name, content literal/regex, symbol definition lines), which maps directly onto the kind enum. The agent can tell this apart from project_read_file and project_list_files 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?

"Use when: ... use kind=literal_content or definition" and "Avoid when: you already know the exact path to read" give both the trigger and the exclusion, and the exclusion implicitly routes to project_read_file. No inference is required.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine context beyond that: the returned status values ('cancellation: accepted, cleanup_complete') and batch behavior. The stray 'Speed: nhanh' line is a non-English artifact that muddies rather than clarifies.

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?

Short, front-loaded, and organized into labeled clauses (Use when / Avoid when / Output / Batch-safe). The 'Speed: nhanh' line is wasted space and inconsistent with the otherwise English text.

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

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

No output schema exists, and the description covers the return fields, so return-value expectations are set. The main remaining gap is the run_id contract, which matters for a single-param tool.

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

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

Schema description coverage is 0% for the single required parameter, so the description should compensate. It only names run_id without explaining format, where to obtain it, or whether it must be an active run — this is the minimum needed to be usable.

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 ('Cancel a running shell command') plus the identifier it keys on ('by run_id'). It is unambiguously distinguishable from siblings like project_shell_status and project_shell_run.

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 gives the positive trigger ('running too long or its result is no longer needed') and a negative trigger ('Avoid when: the command already finished'), and names the alternative tool project_shell_status to check first.

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 destructiveness, open-world, non-idempotent, non-read-only, so the safety profile is covered. The description adds genuinely new behavioral context: ~5 ms return latency, run time equal to the command, async run_id contract, output fields, batch-safety, and a default cwd. Missing timeout/pagination limits or permission notes, 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?

Labeled sections (Use when, Avoid when, Speed, Output, Batch-safe) are front-loaded and scannable. Minor repetition: 'returns run_id immediately' appears twice, slightly blunting the conciseness.

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

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

For a destructive async shell tool with no output schema, the description explains the async flow, the output fields (run_id, running, exit_code, stdout_tail/stderr_tail), and timing. The undocumented 'shell' parameter is the main gap; timeouts and failure handling are also 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%, so the description must compensate. It documents 'command' implicitly and 'relative_cwd' via the '/app' default, but the 'shell' enum parameter (powershell/cmd/bash) is never mentioned in the description or schema. Partial compensation only.

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 immediately distinguishes its async nature from the sibling project_shell_status, which it names explicitly. An agent can tell exactly what this tool 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?

Explains when to use (build/test/lint/long-running commands) and when to avoid (very short commands needing immediate output), and gives the alternative flow (run then poll 0s). Explicit exclusion plus named alternative is the top bar.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses that wait_seconds is an observation window rather than a timeout, that the call is fast and not queued so it never blocks other tools, and describes the output fields (running, exit_code, stdout_tail/stderr_tail). These are non-obvious behavioral traits that materially change how an agent polls.

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 segmented into Use when / Avoid when / Speed / Output / Batch-safe lines. Every line carries distinct information with no repetition.

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

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

For a two-parameter polling tool with no output schema, the description supplies the missing pieces: polling condition, timing semantics, non-blocking behavior, and return shape. Nothing an agent needs to call it correctly 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 coverage is 0%, so the description must compensate, and it does for wait_seconds by explaining the observation-window semantics and the 0..30 bound. run_id is only implied by 'after project_shell_run' and the 'no run_id' exclusion rather than described directly, so it falls just short of full coverage.

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: 'Check status + output of a running command,' which distinguishes it from project_shell_run (start) and project_shell_cancel (abort). An agent can identify the tool's role 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?

Explicitly names the trigger ('after project_shell_run; poll until running=false') and the exclusion ('no run_id available yet'). The sibling it pairs with is named, and the polling loop condition is spelled out.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered; the description adds value beyond that with the cache invalidation side effect ("clears the read/list/search cache for the affected path"), the error behavior of mode=create, and the return payload (action, bytes_written, sha256_after). It also flags "Batch-safe: no", which prevents an agent from looping this in a batch call.

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?

Telegraphic, front-loaded lines with labeled sections (Use when / Avoid when / Speed / Output / Batch-safe) and zero filler. Every line carries actionable information an agent could act on.

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

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

No output schema exists, but the description supplies the return shape and the cache side effect, so the main behavioral unknowns are covered. The gap is expected_sha256 and create_dirs, which matter for a destructive write tool with 20% schema coverage.

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

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

Schema description coverage is only 20%, so the description must compensate: it does explain the mode enum thoroughly (create errors if exists, overwrite replaces, append concatenates), which is the highest-risk parameter. However, create_dirs and especially expected_sha256 (an optimistic-concurrency guard) get no explanation anywhere, so compensation is partial.

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?

"Write a file" pairs a specific verb with a specific resource, and the three mode semantics (create/overwrite/append) are spelled out so the agent knows exactly which variant of writing it is choosing. It also implicitly separates itself from project_edit_file, which appears in the same toolset.

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

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

Explicit "Use when: create a new file or replace/append a file's contents" and "Avoid when: only a small section needs to change (project_edit_file)" names the alternative and the condition that selects it. This is the strongest possible routing guidance.

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