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

Even though annotations already mark destructiveHint=true, the description adds substantial behavioral detail: the confirm='EXECUTE' gate, creation of the database file and parent folder, one-statement-per-call limit, for_each interaction, and logging behavior. This goes well beyond the structured annotations and gives the agent a clear model of side effects.

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

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

The description is long but each sentence earns its place. It front-loads the core purpose and confirm requirement, then covers creation semantics, parameter formats, and advanced for_each behavior without repetition or filler.

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

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

Given five parameters, zero schema descriptions, and destructive behavior, this description is remarkably complete. It covers preconditions, side effects, placeholder syntax, workflow integration, and logging, leaving no critical gap for an agent attempting correct invocation.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameters. It explains sql, confirm, db_path, log_path, and params in meaningful terms, including positional vs named placeholders and the exact confirm value. The for_each usage example further clarifies how params and confirm/log_path behave in a workflow.

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

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

The description opens with a specific verb and resource: 'Runs a single SQL statement that isn't SELECT' and explicitly enumerates the supported statement types. This clearly distinguishes it from the sibling db_query tool, which handles reads, without needing to inspect schemas.

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

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

The description gives clear usage context: use this for non-SELECT SQL statements, and explains how to create a new database by running CREATE TABLE against a non-existent path. It excludes SELECT but does not explicitly name db_query as the alternative, so it stops short of the strongest possible 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=true and idempotentHint=true, so the description's emphasis on read-only is consistent. The description adds valuable behavioral context by explaining placeholder binding behavior (ignoring extra keys in dicts), which is not inferable from schema or annotations. This enriches the agent's understanding without contradiction.

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 concise yet information-dense, front-loading the core purpose and safety constraint (read-only) before diving into usage details. Every sentence contributes to either clarifying purpose or guiding usage, with no fluff or redundancy.

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

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

Given the tool's moderate complexity (3 params, read-only query) and the rich output schema, the description covers all necessary aspects: purpose, parameter binding, and integration with for_each. The annotation covers idempotency, and the output schema likely describes result structure, so nothing critical is missing. The description is complete for effective invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it does excellently. It explains the semantics of the 'params' parameter in detail (list for positional, dict for named placeholders, behavior with extra keys), which is vital for correct usage. It also implies the purpose of sql and db_path through context.

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 (runs), resource (a single read-only SELECT query), and clearly distinguishes itself from siblings like db_execute by emphasizing read-only. The purpose is unambiguous and contextually differentiated.

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

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

Explicitly instructs to use params instead of formatting values into the SQL string, which is critical for safe query construction. It also describes a specific pattern (for_each with item_arg='params') and how to use dicts from get_metadata, giving concrete guidance on when and how to use this tool effectively.

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 and idempotentHint, so the safety profile is handled. The description adds a valuable behavioral caveat — 'Does not create the file if it's missing' — which goes beyond the annotations and helps predict tool 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?

Two sentences, no filler, with the core behavior first and the important side-effect caveat second. Every clause earns its place.

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

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

For a simple read-only one-parameter tool with annotations and an output schema, this is nearly complete. The only minor gap is that the behavior when the file is missing is only partially disclosed — it won't create the file, but whether it errors or returns empty is left unspecified.

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 carries the burden for the single db_path parameter. The wording 'in a SQLite database' and 'file' imply db_path is a path to a SQLite file, but the description never explicitly documents the parameter's type or format beyond the schema's string type.

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

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

The description uses a specific verb ('Lists') and resource ('tables and their columns in a SQLite database'), and immediately clarifies its orientation role before query writing. This clearly distinguishes it from db_query/db_execute and other file operations.

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

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

'Orientation before writing queries' gives a clear context for when the tool is appropriate, but it does not explicitly name alternatives or state when not to use it. The positioning against query/execute siblings is implied rather than explicit.

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 destructiveHint=true, the description discloses the confirmation gate, the no-op behavior without EXECUTE, logging to log_path, and the batch gating semantics. This is safety-relevant behavior that annotations alone do not provide, and there is no contradiction.

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

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

Three sentences with the most important scoping and safety information front-loaded. The phrase 'just like it used to gate the whole batch' is slightly vague but does not add meaningful bloat.

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

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

With an output schema present, return-value details are covered. The description adequately covers the operation, confirmation requirement, logging side effect, and for_each batching. It could be more complete by explicitly routing to files_preview_op for non-destructive checks and clarifying src/dst roles.

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

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

With 0% schema coverage, the description compensates for confirm (must equal 'EXECUTE'), log_path (receives logs), and action (delete/move). However, src and dst are not explicitly defined, and action values are not enumerated despite no enums in the schema, so some parameter semantics are still left to inference.

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

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

The description states a specific verb and resource: 'Executes a SINGLE delete/move operation.' It clearly distinguishes this from a batch or preview tool, and the contrast with the sibling files_preview_op is implicit but strong.

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 says confirm='EXECUTE' is required and nothing happens without it, and it instructs using for_each for many files with shared confirm/log_path. It gives clear usage context, though it does not explicitly name files_preview_op as the safe non-executing alternative.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond those hints: it specifies the exact hash algorithm (SHA1), that it hashes the entire file contents, and that the result is stable regardless of path. This is meaningful behavioral disclosure for a simple read-only operation.

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

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

The entire description is one sentence with no filler. The key fact (full SHA1) is front-loaded, and the secondary purpose (stable identifier independent of path) follows naturally. Every word contributes value.

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

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

For a one-parameter, read-only, idempotent tool with an output schema, the description covers what an agent needs to know: what is hashed, how, and why the result is meaningful. The annotations handle safety, and the output schema handles return values, so nothing essential 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?

The only parameter is 'path' with no schema description, so schema coverage is 0%. The description's phrase 'the file's contents' implies that path must point to a file, which adds some meaning, but it does not specify path format, relative vs absolute paths, or whether the file must exist. For a single self-explanatory parameter, this is adequate but not exceptional.

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

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

The description clearly states the tool computes the full SHA1 of a file's contents, which is a specific, well-defined operation. It also distinguishes this from file I/O and metadata tools by emphasizing content-based identity independent of the file path.

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

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

The phrase 'stable identifier independent of the file path' provides clear context for when to use this tool — when content identity matters rather than location. It does not explicitly name alternatives or exclusions, but the intended use case is strongly 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 readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful context by stating that it returns a list of paths and describing its role as a pipeline producer, which goes beyond the structured 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 sentences with no filler. The core behavior is front-loaded, the pattern example aids comprehension, and the pipeline role is included in the second sentence without bloating the description.

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 search tool, the description covers the main purpose, result type, and usage context. The recursive parameter semantics are not explicitly stated, but the schema default and clear parameter name make this a minor gap rather than a blocking 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 0%, so the description must compensate. It gives a concrete pattern example ('*.epub') and implies folder is the search location, but it does not explain the recursive parameter at all. The parameter names are reasonably self-explanatory, but the description still leaves one parameter's behavior to inference.

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

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

States a specific action and resource: finds files matching a pattern in a folder and returns a list of paths. The producer-for-for_each note also clearly differentiates it from sibling read/write/execute tools.

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 describes when this fits: as the typical producer for for_each steps in run_pipeline. It does not name alternatives to exclude, but the pipeline usage context is clear enough for an agent to choose it appropriately.

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

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

The description explicitly says it 'changes nothing on disk', which matches the readOnlyHint=true annotation and adds user-facing assurance. It also discloses the exact checks performed: file existence and size. This adds meaningful behavioral context beyond the annotations, though it does not discuss error behavior or edge cases.

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 efficient, front-loaded sentences. The core behavior, safety guarantee, and usage pattern are all stated without fluff. 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?

The tool has annotations and an output schema, so the description does not need to explain return values or safety details. However, the missing 'dst' semantics and lack of explicit action values leave the description incomplete for correct invocation, especially for move operations.

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

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

Schema description coverage is 0%, so the description must compensate. It partially clarifies 'action' (delete/move) and 'src' (the file to check), but it never explains the 'dst' parameter, when it is required, or how it behaves for move versus delete. This is a significant gap for a 3-parameter tool.

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

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

The description clearly states a specific operation: 'Preview of a SINGLE delete/move operation' and explains what it does ('checks whether the file exists and how big it is'). It also distinguishes itself from the sibling files_execute_op by saying this runs 'before execute_op', making its role unambiguous.

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

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

The description gives explicit context: use it with for_each to check multiple files before execute_op. This is clear when-to-use guidance. It does not explicitly state when not to use it or list alternative tools, but the reference to execute_op makes the intended workflow evident.

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, openWorldHint, and idempotentHint, and the description does not contradict them. It adds useful behavioral context: total_lines is exposed to indicate file size, non-text files cause clear errors rather than garbage output, and reading is presented as a non-destructive operation. This exceeds the annotation baseline.

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 well-structured and front-loaded. The first sentence states the core behavior, the second adds size-scoping guidance, the third clarifies error behavior, and the fourth gives a concrete workflow pattern. Each sentence earns its place without redundancy.

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

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

Given the output schema exists and the annotations cover the tool's side-effect profile, the description supplies the remaining context needed: how to handle large files, what to expect when reading non-text files, and why this tool is useful for token-efficient summarization. An agent has enough information to invoke it correctly and choose a sensible invocation strategy.

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 semantics. It explains start_line and max_lines as a line-range window and max_chars as a cap, and it references total_lines as a sizing signal. Path is self-evident from the schema. It does not spell out edge cases like how multiple limits interact, but the core meaning of every parameter is present.

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

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

The description opens with a specific action and resource: 'Reads a text file'. It goes beyond the title by defining the optional windowing/capping behavior and by making the text-file scope explicit, which differentiates it from write, preview, and binary-file operations. There is no ambiguity about what the tool does.

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

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

The description gives a clear usage context: read files, optionally window them for large files, and pair with for_each + build_prompts + ask_llm to summarize many files cheaply. It does not explicitly say when to avoid this tool or name a sibling alternative such as files_find_files or files_preview_op, so it stops just short of a 5.

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

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

The description correctly and helpfully reveals destructive behavior (overwrite replaces the whole file), the confirmation requirement, and parent-folder creation. However, it explicitly describes mode='append' as adding to the end, which is not idempotent, while the annotations declare idempotentHint=true. This is an annotation contradiction that can mislead an agent into retrying a call and duplicating content.

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

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

The description is compact and well-ordered: purpose first, then behavioral details, then a useful orchestration note. Each sentence adds information, and there is no filler or repetition of schema fields.

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?

Coverage of all parameters and effects is strong, and the output schema handles return-value details. The only notable contextual deficiency is the conflicting idempotentHint, which raises ambiguity about safe retry behavior; otherwise the description leaves little unexplained.

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

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

Schema description coverage is 0%, so the description must carry the burden—and it largely does. It explains the meaning of mode, the exact required value for confirm, and the path/content separation. It does not detail path formatting or encoding constraints, but those are unlikely to be essential for correct invocation.

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

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

The description opens with a specific verb and resource: 'Writes text to a file.' It then clarifies the two modes (overwrite/append) and even differentiates its argument style from db_execute's dict-style params, making the tool's purpose and identity 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?

It gives concrete usage guidance: when to use overwrite vs append, that confirm='EXECUTE' is required, and that parent folders are created automatically. It also explains the for_each pattern, though it does not explicitly name alternative file-writing tools or state when not to use this tool.

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 indicate read-only and idempotent behavior. The description adds meaningful context beyond those annotations by disclosing that dependency folders like node_modules and .venv are skipped by default, which is a key behavioral trait an agent must know.

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 two sentences with no wasted words. It front-loads the core output and then states the important default behavior, making it easy for an agent to grasp quickly.

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

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

With an output schema present, return value details are covered elsewhere. However, the description omits usage guidance and details about max_depth/max_items semantics, so an agent may not know how to tune the analysis. It is adequate for default usage but not fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only clarifies skip_dependency_dirs by giving examples of dependency folders; path, max_depth, and max_items are left entirely to inference from their names and defaults.

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

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

The description clearly states what the tool does: produces a folder breakdown by file extension (count/size/%) plus a structure tree. This distinguishes it from sibling tools like files_read_file and files_find_files, though it does not explicitly name an alternative or use a crisp imperative verb.

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

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

There is no guidance on when to use this tool versus alternatives such as files_find_files or files_read_file. The note about skipping dependency folders hints at behavior, but it does not explain use cases, exclusions, or when a sibling tool would be more appropriate.

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 annotation, the description explains a nuanced default behavior: model=None queries /v1/models to reuse whatever model is already loaded, avoiding a model swap or extra RAM usage. This is valuable behavioral context not available in the schema or 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?

The description is front-loaded with the primary purpose and then provides a detailed, relevant explanation of the model default. It is slightly dense and runs on in places, but every sentence contributes useful information.

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

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

For a read-only query tool with an output schema, the description covers the main usage context and the key model-selection behavior. It could add notes on error handling or timeout behavior, but those are less critical given the output schema and simple operation.

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

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

With 0% schema description coverage, the description carries more responsibility and does explain the model parameter in depth, including its default and override behavior. However, it does not add meaningful semantics for prompt, timeout, or base_url, leaving those to the schema/defaults.

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

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

The description clearly states the action ('Short query to the local model') and the intended use case ('quick, simple decisions/classification inside a pipeline'). It also references the sibling build_prompts tool contextually, which helps orient the agent, though it does not explicitly contrast itself with alternatives.

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

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

It gives concrete usage guidance: 'Use with for_each after build_prompts to ask about many items at once.' This clearly places the tool in a pipeline workflow and implies when it is appropriate, but it does not state exclusions or name when a different tool should be used instead.

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 idempotentHint=true, so the safety profile is covered. The description adds useful behavioral detail: it uses Python str.format semantics, handles plain vs dict items differently, and produces multiple prompts from one template. This goes beyond the annotations without contradicting them.

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

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

Three sentences, each earning its place: mechanism, pipeline context/benefit, and placeholder rules. The most important information is front-loaded, and there is no redundant restating of the title or schema.

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

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

For a two-parameter tool with an output schema, the description is sufficiently complete. It specifies inputs, placeholder behavior, and where the tool fits in a larger flow. Remaining details like exact output format are covered by the output schema, so nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It explains both parameters: 'template' is the Python format string, and 'items' is a list that can contain plain values for positional placeholders or dicts for named placeholders. The example with read_file dict items adds real semantic value beyond the bare schema.

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

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

The description states a specific verb and resource: it 'fills a template (Python str.format) with each item in a list.' It also differentiates from sibling llm_ask_llm by positioning itself as a step between a producer and ask_llm in a for_each flow. This makes the tool's role unambiguous.

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

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

The description gives clear context: use it in a for_each pipeline to build N prompts without hand-typing them, before calling ask_llm. It does not explicitly list when-not-to-use cases or name an alternative tool, but the intended usage is clear enough for an agent to decide when it applies.

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 read-only and idempotent behavior. The description adds useful behavioral detail beyond those annotations: it guarantees path/name/size/type, makes output type-dependent, and specifies flattening. It does not cover error or unsupported-type behavior, but the annotations lower the burden.

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 two sentences with no filler: it front-loads the purpose, lists supported formats, then states the guaranteed output and the flattening behavior. Every phrase 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?

Given an output schema exists and the annotations cover safety, the description supplies sufficient context: supported types, guaranteed core fields, and output flattening. Minor ambiguity around unsupported file types and path expectations keeps it from being fully complete.

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

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

The input schema has only a required string 'path' with no description, and the tool description does not define path syntax, scope, or allowed forms. The description's mention of 'path' in the output is an indirect clue, and the single conventional parameter is understandable, but with 0% schema description coverage the description does not fully compensate.

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

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

The description clearly identifies the tool as a file metadata provider and enumerates supported formats (epub, m4b, PDF, DOCX) and common output fields. It does not use an explicit verb like 'retrieves' or 'returns', and it does not explicitly contrast itself with sibling tools, so it stops short of a 5.

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

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

The format list gives concrete applicability: agents can infer they should use this tool when needing metadata for epub, m4b, PDF, or DOCX files. It does not explicitly name alternatives or say when not to use it, so it lacks the explicit when/when-not guidance required for a 5.

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

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

The description goes well beyond the annotations by explaining non-obvious behaviors: for_each spreads item dict keys as keyword arguments, results include identifying fields to disambiguate items, and exceptions do not abort the whole pipeline but become ok=False/error in the step result. This is exactly the kind of behavioral context an agent needs and the annotations do not provide.

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 with the core action. Every clause adds meaningful semantic detail, though the middle section is a long, complex sentence that could be broken into clearer bullet points. It is efficient given the complexity of the tool.

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

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

The description covers ordering, step construction, result naming, iteration over prior results, argument mapping, result disambiguation, and error handling. The presence of an output schema means return-value documentation is not required, and the description otherwise gives an agent everything needed to construct a valid pipeline 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 0%, so the description carries the full burden for parameter semantics. It explains steps, block, args, save_as, for_each, item_arg, and the result shape in substantial detail, far exceeding the bare JSON schema definitions. It also clarifies subtle interactions like the '@name.field' reference syntax and keyword spreading.

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

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

The description opens with a specific verb and resource: 'Runs a list of steps in order.' It then defines what each step contains (block, args, save_as, for_each), making the tool's purpose unmistakable. It is clearly differentiated from the sibling file/db/llm tools by its orchestration role.

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

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

No explicit guidance about when to use this tool versus alternatives, nor any when-not-to-use or exclusion criteria. The orchestration purpose is implied by 'Runs a list of steps in order,' but the description never tells an agent to choose this over calling individual blocks directly or using another tool.

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