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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description still adds real value beyond them: it confirms parent creation (mkdir -p semantics), restates idempotency as 'existing one is not an error', and discloses a policy-based permission failure mode not captured in the annotations.

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

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

Two short clauses, front-loaded with the core action and behavior, with zero filler. Every clause carries distinct information (recursive creation, idempotency, authorization failure).

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

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

For a simple one-param mutation with no output schema and rich annotations, the description covers behavior, idempotency, and failure modes well. The only meaningful omission is what form 'path' must take and where writing is permitted.

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

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

The single 'path' parameter has zero description coverage in the schema, and the description supplies no semantics either — no indication of relative vs absolute paths, allowed roots, or format. With one undocumented param and 0% coverage, the description fails to compensate 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 clear verb+resource ('Create a directory') and immediately extends it with recursive behavior ('and parents'). No sibling in the list performs directory creation, so the tool is functionally distinguishable, but the description never routes the agent relative to any sibling, keeping it a notch below a 5.

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

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

Usage is only implied: the agent learns an existing directory is not an error and that zone policy can refuse the write, but there is no explicit when-to-use, when-not-to-use, or alternative named. It is adequate context without 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds the depth cap (2 levels) but says nothing about symlink handling, permission errors, or output volume for large trees.

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

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

Two compact fragments, front-loaded with the core behavior and immediately followed by the alternative. No sentence 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 simple read-only listing tool with no output schema, the description covers the essential behavior and depth limit. It omits path format expectations and rough output shape/size, which are the remaining gaps for an agent to call it confidently.

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

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

There is one required parameter, path, with 0% schema description coverage, and the description never mentions it. It does not specify whether the path must be absolute, relative, or within an allowed directory, leaving the agent to guess.

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

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

States the specific behavior (recursive tree view) and scope (2 levels deep), which distinguishes it from shallow-listing siblings. The verb 'view' is weak but the resource and recursion behavior are unambiguous.

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

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

Explicitly routes the agent to the sibling list_directory for one-level listings, giving a clear selection rule. It does not state exclusions or prerequisites for this tool itself, so it falls short of full when/when-not coverage.

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 flag destructive/non-idempotent, and the description adds substantial context beyond them: atomic bottom-up application so grep/read line numbers stay valid, stale rev rejection (never partially applied), the return value (new rev), dryRun diff preview, and per-zone policy behavior. This is exactly the operational detail a mutating tool needs.

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 purpose and the two shapes, and nearly every sentence carries operational meaning. The density is high and the zone-policy clause packs several rules into one sentence, but nothing is padding.

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

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

For a mutation tool with no output schema, the description covers input shapes, preconditions (rev), atomicity, failure behavior, the return value (new rev), dry-run, and the sibling alternative. An agent has everything required to call it correctly.

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

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

Schema coverage is only 25% (rev is the sole documented param), so the description carries the burden and delivers: oldText/newText literal replacement, startLine/endLine inclusive range replacement, newText "" meaning delete with no trailing newline, and the insert/append edge cases. It fully compensates for the schema gap.

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

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

States a specific verb+resource ("Edit a file") and immediately enumerates the two mutually exclusive edit shapes. It distinguishes itself from the sibling write_file explicitly ("To replace a whole file use write_file") and notes document formats are read-only, so an agent can place it against write_file without opening 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?

Gives concrete when-to-use rules for each shape, the exact conditions that select insert-vs-replace (omitting endLine inserts; startLine = lines+1 appends), the rev requirement for line edits, and the zone-policy exceptions (overwrite="rev" always needs rev; overwrite="never" refuses edits). It also routes whole-file replacement to write_file.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read profile is covered. The description adds return-shape context and hints at a 'rev' relevant to a strict-zone write workflow, but that note is too cryptic to be actionable and nothing else behavioral (errors, symlink handling) is disclosed.

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 single sentence that leads with what metadata is returned and ends with the sibling routing. The garbled parenthetical about 'strict zone' is the only wasted and confusing fragment.

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 enumerates the return fields (size, times, format, line count, rev), which is exactly the burden it must carry, and annotations cover safety. The one weakness is the missing path semantics, but overall it is sufficiently complete for a one-param read tool.

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

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

The single 'path' parameter has 0% schema description coverage, so the description must carry the meaning, and it only implies via 'file or directory' that path accepts both. No syntax, relative-vs-absolute, or allowed-root guidance is added, leaving the one required param under-specified.

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

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

States a specific verb+resource ('Metadata for a file or directory') and enumerates returned fields (size, times, format, line count, rev), which cleanly distinguishes it from read_text_file, named explicitly for content. The cryptic parenthetical 'the rev that writes in a strict zone ask for' slightly muddies an otherwise clear purpose.

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

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

It routes content reads to read_text_file ('Content: read_text_file'), which is real usage guidance pointing at an alternative. However, it gives no when-to-use vs the other metadata-adjacent siblings (list_directory_with_sizes, directory_tree) and no explicit exclusions beyond the content case.

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, idempotentHint, non-destructive behavior, and openWorldHint false. The description goes well beyond them by describing return structure per file, line clipping behavior, document extraction notation, skipped file types, and capped output with truncation signaling.

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 dense but front-loaded and every sentence contributes operational value: search scope, return format, document behavior, skip rules, truncation, and the sibling alternative. There is no filler or repetition of schema fields for their own sake.

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 and 9 parameters, the description provides the missing return-value context: per-file path, rev, line count, matching lines, document match notation, clipping, and truncation. Combined with annotations covering safety, an agent has what it needs to call and interpret 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 description coverage is 89%, so the schema carries most parameter semantics. The description still adds useful meaning for max_line_length clipping, documents:false, and how line numbers/rev feed into read_text_file and edit_file, though it does not add much detail for context, exclude, include, ignore_case, or max_results 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: 'Search file CONTENTS by regex, recursively.' It distinguishes itself from search_files explicitly with 'To find files by name use search_files,' so an agent can tell it apart from the sibling that finds files by name rather than by content.

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 context: content search by regex. It names the alternative search_files and the condition that selects it, and it notes documents:false behavior plus skips for other binaries and symlinks, so exclusions are explicit rather than inferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety and idempotency are covered. The description adds a genuinely useful constraint ('every path must be inside it'), but does not describe the return shape or that results are directory paths.

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

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

Two short clauses, front-loaded with the core concept and the constraint, then the usage cue. No wasted words.

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

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

No output schema exists, so the description bears the burden of conveying what is returned; it hints at 'the vault root' but never states that the tool returns a list of permitted directory paths, which is the agent's main need. Adequate for a zero-param read tool but leaves the return semantics underspecified.

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 and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline of 4 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 name and title ('List allowed directories') carry the specific verb+resource, but the description itself is a noun fragment ('The vault root') rather than a stated action. It conveys the concept of the allowed/vault root directory and distinguishes it from path-scoped siblings, but an agent reading only the description gets an implied rather than explicit purpose.

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

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

'Start here if the vault path is unknown' gives an explicit trigger condition for when to call this tool first. It stops short of naming alternatives or exclusions (e.g., versus list_directory), so it is clear context without 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?

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds a real behavioral trait beyond them: the first output line carries the policy in force, and "list one directory" signals non-recursive scope. It stops short of permissions or error behavior, but that is a minor gap given annotation coverage.

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

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

One sentence, zero filler, and the scope statement is front-loaded before the alternative-routing clauses. Every fragment 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 simple read-only, no-output-schema tool, the description covers scope, sibling routing, and a notable return characteristic. Only path constraints and failure behavior (e.g. nonexistent path) are left 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 description coverage is 0% for the single required parameter, so the description must compensate; it only weakly implies the value is a directory. It gives no guidance on path format (absolute vs. relative, must be inside an allowed directory) even though a list_allowed_directories sibling exists.

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 one directory") and immediately distinguishes the operation from its nearest siblings by naming them. An agent knows this is a single-level listing, not a recursive walk or a size-annotated listing, 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?

Names both alternatives with the exact condition that selects each: list_directory_with_sizes when sizes matter, directory_tree for deeper levels. This is explicit routing rather than implied usage, so the agent can pick the right sibling directly from the text.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds the sorting behavior but says nothing about output format (e.g., size units), recursion, or symlink handling. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two tight sentences, front-loaded with the core capability and followed by the routing hint. No wasted words.

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

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

For a simple read-only listing tool whose annotations cover safety, the description is nearly complete: capability, sorting, and sibling routing are all present. It could mention the size unit or non-recursive scope, but no output schema exists so return-value detail is not strictly required.

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

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

Schema description coverage is 0%, so the schema documents only types and the sortBy enum. The description does add meaning by pairing 'file sizes' with the sortBy values ('sorted by name or size'), partially tying the enum to intent, but it says nothing about the required path parameter.

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

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

States a specific verb and resource ('List a directory'), names the distinguishing feature (with file sizes), and immediately contrasts with the sibling list_directory. An agent can tell it apart from list_directory without opening 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?

It explicitly routes the agent to the alternative tool when sizes aren't needed ('Without sizes: list_directory'), which is clear guidance. It does not state when to prefer sortBy=size vs sortBy=name, but the primary tool-selection decision 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?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuine policy context beyond that: rev is required when leaving a zone with overwrite="rev", and directories cannot leave a strict zone. It stops short of explaining destination-overwrite or failure behavior.

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

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

Front-loaded with the core verb+resource, then the zone/rev constraint, then the alternative-tool guidance. Every clause carries information, though the 'exactly like overwriting it in place' aside is slightly dense and could be trimmed.

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, so the description is the only source of behavioral detail, and it covers the non-obvious zone/rev constraint and the trash interplay well. It omits destination-overwrite semantics and error behavior, minor gaps for an otherwise well-covered mutation 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 only 33% (source and destination undocumented), so the description must compensate. It does add real meaning for rev ('requires its current rev, exactly like overwriting it in place'), but says nothing about source or destination, leaving the low-coverage gap only partly filled.

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 pair ('Move or rename a file or directory') that is immediately distinguishable from siblings like trash_file and write_file. An agent knows exactly what class of operation this is 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 alternative ('Use trash_file, not this, to discard something') and adds the inverse rule (moving a file out of the trash restores it), giving both a when-not and a behavioral side effect. Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — deprecation status — but says nothing about how head/tail/limit/offset interact, so it adds only modest context beyond the annotations.

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

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

A single short sentence, front-loaded with the most decision-relevant fact (DEPRECATED) before the alias target. It is well-sized for a redirect, though the brevity comes at the cost of any parameter or behavior detail.

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

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

For a deprecated alias with rich annotations and no output schema, a one-line redirect is defensible, and deferring detail to read_text_file is reasonable. However, the five undocumented parameters mean an agent cannot verify whether head/tail/limit/offset are honored here without opening the sibling 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?

Five parameters with 0% schema description coverage, and the description gives no meaning for any of them. The only indirect help is the 'alias of read_text_file' claim, implying the same signature as that tool, which an agent could infer but is never stated.

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 plainly that this is a deprecated alias of read_text_file, which tells an agent exactly what it is and how it relates to a named sibling. It stops short of describing the read behavior itself, relying on the name/title for the verb+resource, so it is clear but not fully self-contained.

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?

Marking the tool DEPRECATED and naming read_text_file as the aliased tool effectively routes the agent to the non-deprecated sibling. It does not spell out an explicit 'use X instead' instruction or any exclusion, so it is strong but not complete 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuine behavioral detail beyond them: a PDF yields one page (default 1) rendered as JPEG plus the total page count. It does not describe what images/audio return, so it is not a full 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?

Two sentences, front-loaded with the capability, followed by return behavior and then alternatives. No filler, every clause earns its place.

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

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

For a one-parameter read tool with full annotation coverage and no output schema, the description covers capability, PDF return behavior, and routing. The only gap is what is returned for image and audio inputs, which is left 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 description coverage is 0% for the single 'path' parameter, so the description must compensate and it does: it documents the '#N' path suffix convention for selecting a PDF page and the default of page 1. That is a real semantic addition the bare schema lacks.

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

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

States a specific verb and resource set ('Read an image, audio or PDF file') and immediately names the two PDF-oriented siblings it is not (read_pdf_text, read_pdf_page). An agent can tell this apart from the other read tools 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?

Explicitly routes the agent: PDF text goes to read_pdf_text, a single PDF page as an image goes to read_pdf_page, and this tool handles images/audio/whole-PDF-as-media. The when-not condition for the named alternatives is stated 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 already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real context beyond that: output is rendered as numbered lines matching read_text_file, only whole files are read, ranges are unsupported, and trashed items are excluded.

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 terse sentences, front-loaded with the capability and immediately following with the routing rule; the parentheticals carry distinct constraints without 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 cover the return rendering (numbered lines) plus the trash exclusion, so the main unknowns are filled. It omits failure/ordering behavior for partial matches, a minor remaining gap for a read-only batch 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% and the description says nothing about the sole required 'paths' array: ordering of results, whether directories or globs are accepted, or what happens when a path is missing. With one undocumented parameter, the description should compensate and does not.

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 several whole files at once') and constrains scope ('whole files', output as numbered lines, trash skipped), which cleanly separates it from the single-file and range-based 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?

Explicitly routes to read_text_file for line ranges or rev, and notes the trash is skipped. It does not address the singular read_file sibling, but the when-to-use condition for the range case is stated outright.

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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds value beyond them by disclosing the return format (JPEG image) and the 1-based page numbering, which prevents off-by-one errors. It does not mention resolution/quality or size of the rendered output.

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

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

Two tight sentences with zero filler. The core behavior (what is rendered, in what format, with what indexing) is front-loaded ahead of the alternative-tool guidance.

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 states the return type is a JPEG. Both parameters are at least partially addressed and the sibling relationship is resolved, leaving only rendering options (resolution, color) unmentioned, which the schema itself does not expose either.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It clarifies that 'page' is 1-based, which is genuinely useful, and 'path' is inferable as the PDF location, but no format or path-constraint detail is given for either parameter.

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

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

States a specific verb (render), resource (one PDF page), and output format (JPEG), plus the 1-based indexing convention. It also names the sibling tool it is not (read_pdf_text), so an agent can distinguish it without opening 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?

Explicitly routes between alternatives: 'Prefer read_pdf_text unless layout or graphics matter.' The condition that selects this tool over the text extractor is stated 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the return format (numbered lines with page markers) and the cost/performance tradeoff versus page images, though it does not discuss pagination or very large files.

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 core function, then the output format, then the routing guidance. Every clause earns its place 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 explains the return format, and annotations cover safety; the main gap is the undocumented page-range parameters. Sufficient for correct invocation, short of 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 0%, so the description must carry the parameters. It signals that a page range is supported via 'whole or a page range', mapping to first_page/last_page, but does not name them, state defaults, or clarify inclusivity. 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 (text of a PDF, whole or page range) and describes the output shape (numbered lines with page markers). It explicitly distinguishes itself from read_pdf_page (for scans) and links its numbering to read_text_file, so an agent can tell it apart from siblings without opening schemas.

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

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

Gives explicit when-to-use guidance ('prefer it' because it is cheaper than page images) and names the alternative with its own selecting condition ('for scans use read_pdf_page'). Nothing about tool selection is left to inference.

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

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

Annotations already cover readOnlyHint, idempotentHint and destructiveHint=false, so safety is handled. The description adds genuinely new behavior: documents come back read-only with no rev, offset/limit reports total lines and rev (required for edit_file line edits), and HTML/RTF/EML/FB2 read raw unless extract:true. It stops short of describing pagination or exact return shapes, but the important rev/read-only nuances are disclosed.

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

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

A single front-loaded paragraph that begins with the core action and then layers modes, content-type behavior, and sibling routing. Dense but essentially every clause carries information; the long compound sentences slightly hurt 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?

No output schema exists, so the description correctly mentions return-relevant facts (total lines, rev, numbered lines with section markers) and rev's role for edit_file. It is nearly complete for a 6-param read tool, though it never clarifies its relationship to the read_file sibling, leaving one ambiguity.

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% (head, tail and path are undocumented in the schema), so the description must compensate. It does: head/tail = 'N lines from an edge', offset/limit = 'an arbitrary 1-based line range', and extract:true = their text for HTML/RTF/EML/FB2. Only the interplay/precedence between head and tail and limit is left implicit.

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

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

States a specific verb and resource ('Read one file') and then enumerates the distinct read modes (whole file, head/tail edge slices, offset/limit 1-based ranges, document/HTML/RTF handling). An agent can tell exactly what the tool does and how it differs from read_multiple_files, read_media_file, and read_pdf_page.

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 to alternatives with conditions: 'Several files at once: read_multiple_files; images and page images: read_media_file / read_pdf_page.' It also states which modes apply to which content types (documents vs HTML/RTF/EML/FB2), leaving little 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, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered structurally. The description adds two genuine behavioral traits not in the annotations: the search is recursive and matching is a case/substring match on the name. It says nothing about result limits, ordering, or what happens on no match.

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

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

Two short sentences, zero filler, with the scope constraint front-loaded and the disambiguation trailing. Nothing could be removed without losing information.

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

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

For a 3-parameter tool with 0% schema description coverage and no output schema, the description is too terse: excludePatterns and path semantics are absent, as is any note on return shape or result limits. The annotations carry the safety profile, but the parameter documentation gap remains a real risk of misuse.

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

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

Schema description coverage is 0% and the description only partially compensates, clarifying that 'pattern' is a name substring. It never explains 'path' (root of the recursion?) or 'excludePatterns' (what forms are accepted, whether globs), leaving two of three parameters with no documented meaning anywhere.

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

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

States a specific verb and resource ('Find files') plus the matching scope ('by NAME substring, recursively'), and explicitly names the sibling it is not (grep_files for content). An agent can distinguish it from grep_files without opening 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?

'For content use grep_files' gives an explicit alternative and the condition that selects it, which is exactly the routing decision an agent faces here. It stops short of exclusions (e.g., versus list_directory or get_file_info), 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?

Annotations only declare read-only/idempotent/non-destructive; the description goes far beyond that by disclosing the statement wrapping (SELECT * FROM (...) LIMIT limit+1), the meaning of the truncated flag, the partial-semicolon rule, rejection of bind parameters, BLOB handling, and the WAL temporary-copy behavior surfaced as wal_copy. This is exactly the extra behavioral 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?

Every sentence delivers a distinct operational fact and the most load-bearing constraint (read-only, allowed prefixes) is front-loaded. Despite its length, there is no filler or restatement of the title.

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

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

With no output schema, the description carries the return-value burden itself and does so: it explains the wrapping/limit semantics, the truncated flag, and the wal_copy field for WAL databases. An agent has enough to call the tool and interpret results without further context.

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

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

Schema coverage is 50%: limit and timeout_ms are documented in the schema, but sql and path are not. The description compensates for sql (allowed prefixes, no placeholders, literal values required, semicolon constraints) and path (a SQLite file, WAL journaling), but never explains timeout_ms, leaving one parameter undocumented in both places.

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 first sentence gives a specific verb, resource, and execution mode ("Run one read-only SQL statement on a SQLite file") and immediately names the enforcement flags (sqlite3 -readonly -safe -json). An agent can distinguish this from the sibling sqlite_schema, which lists schema rather than executing arbitrary queries.

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 constrains when the tool applies by enumerating the allowed statement prefixes (SELECT, WITH, VALUES, EXPLAIN) and stating that escapes/pragmas and bind parameters are rejected. It does not, however, route the agent to the sibling sqlite_schema for schema inspection or state what to do when a query is rejected.

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 cover read-only/idempotent/non-destructive, yet the description adds substantial context: file type from the first 16 bytes rather than the extension, WAL databases read from a private copy cleaned up afterward, 'nothing is ever left next to the original', and the counts_incomplete reporting shape. This is far beyond what the annotations convey.

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 purpose, then behavior, then the counts caveat — the ordering is logical. It is dense and long, and the counts-timeout explanation repeats part of the schema description, but nearly every sentence carries operational information an agent needs.

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 carries the full burden of explaining returns, and it does: table/index/view/trigger DDL from sqlite_master, PRAGMA values, sqlite3 version, path/size/mtime, wal_copy fields, and counts_incomplete. Nothing material to correct invocation 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 67% and the description meaningfully deepens it: counts is a full table scan that 'can take minutes', and counts_timeout_ms is a per-table budget covering sqlite3 spawning and file opening, so 'a very small budget can time out even a tiny table'. It also compensates for the undocumented path parameter's role.

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 ('Inspect a SQLite database file') and immediately scopes it ('schema-neutral, no interpretation of the data'), which implicitly separates it from the sqlite_query sibling. It does not name that sibling explicitly, so differentiation requires a small 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?

Gives explicit operational guidance: 'Call once without counts first, then again with counts only if row counts are actually needed', plus the warning that a second call re-sends the full DDL on a hundred-table database. It stops short of naming an alternative tool for data (not schema) reads, so it is strong but not complete 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?

Annotations already flag destructive=true and idempotent=false, but the description goes further: it explains why it is non-idempotent (an arrival timestamp is appended to the name), that the relative path is preserved, that it fails when no trash exists, and that a prior read is needed to supply rev. These are behavioral facts an agent cannot derive from the annotation block.

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 compact sentences, zero filler, front-loaded with the core action before the failure modes, rev requirement, and restore route. Each sentence carries a distinct constraint the agent needs.

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 two-parameter tool with no output schema, the description covers the action, the naming side effect, the failure condition, the conditional parameter requirement, and the recovery path. Nothing an agent needs to invoke this safely 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 only 50% — rev carries a schema description but path has none. The description compensates by explaining the conditional meaning of rev (required only in overwrite="rev" zones, and it is the current rev you must read first) and by noting path's relative-path preservation. That is more than the schema alone offers, though path semantics remain thin.

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 and resource ("Discard a file by moving it into the trash of its own zone") and immediately separates itself from the sibling move_file by framing this as the removal path. The note that there is no delete operation tells an agent exactly which tool covers file removal.

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 when-to-use ("this is the only way to remove something"), the precondition that fails the call (zone has no trash configured), the conditional requirement for rev in overwrite="rev" zones, and the alternative path for undo ("To restore, move_file it back out of the trash"). Nothing about tool selection is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds real beyond-annotation context: the rev-gated overwrite policy, the refusal message carrying the rev to reuse, and that PDF/DOCX are not overwritten. It stops short of describing return format or partial-write behavior, so a 4 is warranted.

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 action in the first sentence, then adds the rev policy and the edit_file redirect. Three compact sentences with no filler, though the rev-policy clause is dense and could be slightly tighter.

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 mutation tool with no output schema, the description covers the key gotchas: overwrite policy, rev requirement and recovery, sibling routing, and excluded document formats. It leaves the return behavior unspecified, but an agent has enough to call it safely and 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 only 33%, so the description must compensate for rev, path, and content. It explains when rev is required and why (rev policy on overwrite), complementing the schema's note on where to obtain the rev, and the create-vs-overwrite distinction clarifies content semantics. path/content remain self-evident from their 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?

States a specific verb pair (create/overwrite) and the resource (file) with the content scope. It also distinguishes itself from siblings by naming edit_file and clarifying that document formats are excluded, so an agent can separate it from read tools and edit_file.

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 in-file changes to edit_file and lays out the condition under which rev is required (overwrite='rev' policy on an existing file, not on creation). The refusal-message guidance tells the agent how to recover, which is strong when-to-use/when-not coverage.

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