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

Even with annotations already signalling open and destructive behavior, the description adds substantial operational detail: commands are stateful, status and cwd are always returned, output may be truncated, background commands run in new non-reusable shells, and status must be polled before interrupting. These behaviors go well 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?

The bulleted format is front-loaded with the most critical caveat (statefulness) and each subsequent bullet carries actionable information for a high-complexity tool. There is minor redundancy between the one-command-at-a-time and wait-for-previous bullets, but overall the length is warranted by the tool's parameter count and interactive modes.

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

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

For a 10-parameter tool with no output schema, the description does well to state that status and cwd are returned and to cover truncation, backgrounding, and status polling. The main gap is that the interactive input modes (send_text, send_ascii, send_specials) and wait_for_seconds are never explained in context, so an agent may not know how to drive an already-running command.

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 roughly 80% schema coverage the baseline is 3, but the description adds useful parameter semantics: status_check must be called with an empty command argument, bg_command_id is the handle for interacting with a background command, and only one command may run at a time. However, it does not explain wait_for_seconds or how send_text/send_ascii/send_specials should be used with a running process.

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 'Execute a bash command', a specific verb+resource, and immediately distinguishes the tool from file-focused siblings by forbidding echo/cat and directing the agent to ReadFiles/FileWriteOrEdit. It also clarifies stateful execution, which sets expectations beyond what the name alone implies.

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 names ReadFiles/FileWriteOrEdit as the alternatives for file I/O and instructs against shell backgrounding with '&'. It lacks an explicit 'when not to use' statement for the other sibling tools, and the background instruction ('instead use this tool') is slightly ambiguous, though the intent is recoverable from the schema's is_background field.

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?

Annotation Contradiction: the annotations declare readOnlyHint=true, yet the description says the tool 'saves' content into a single text file, implying a file-writing side effect. This directly contradicts the read-only hint. The description also does not clarify whether it reads from disk, writes a new file, overwrites anything, or what side effects occur.

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

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

The description is short, front-loaded with the core purpose, and uses bullets for parameter-specific guidance. It earns its length, but the sentence 'Provide random 3 word unique id or whatever user provided' is slightly informal and could be clearer about whether the id is required or user-supplied.

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

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

For a tool with no output schema and a read/write ambiguity, the description omits important context: where the text file is saved, what happens after saving, how globs are resolved relative to project_root_path, and whether this is a mutating action. The contradiction with readOnlyHint makes the overall behavior especially incomplete for an agent deciding whether to call it.

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

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

With 0% schema description coverage, the description must compensate, and it does: it explains thread_id as coming from Initialize, id as a random 3-word unique identifier, project_root_path as optional/empty when no project path, and relevant_file_globs as file paths or globs. It does not fully define every parameter's format, but adds substantial meaning beyond the raw 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 action: saving a description and file contents into a single text file. It clearly identifies the inputs (description, file paths/globs) and output artifact. However, it does not explicitly distinguish itself from FileWriteOrEdit or explain exactly what 'save' produces or where, 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 bullets give conditional usage hints such as using the thread_id from Initialize and leaving project_root_path empty when absent. However, there is no explicit guidance on when to use this tool versus sibling tools like ReadFiles or FileWriteOrEdit, and no exclusions or alternatives are named.

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

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

Annotations specify destructiveHint: true, and the description details the editing process (full content replacement or search/replace). It explains the behavior regarding percentage threshold and formatting rules. No contradiction with annotations. The description adds context beyond annotations, such as the SEARCH/REPLACE format requirements.

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 quite long but well-structured with bullet points, headings, and an example. It is front-loaded with the main action and then details. While every part serves a purpose, it could be slightly more concise without losing necessary 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?

Given the tool's complexity (4 parameters, destructive behavior, no output schema), the description covers the editing method, percentage calculation, and formatting rules thoroughly. It lacks information on error handling, file creation behavior (if file doesn't exist), and return values, but these are minor gaps.

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?

Although schema descriptions cover all parameters (100% coverage), the description significantly enhances meaning by explaining how percentage_to_change is calculated, the two modes for text_or_search_replace_blocks, and providing a full example with search/replace block rules. This goes well beyond the schema's brief descriptions.

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 writes or edits a file, with specific instructions on using percentage-based changes. It distinguishes itself from siblings like BashCommand (shell commands) and ReadFiles/ReadImage (reading), leaving no ambiguity about its 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?

The description provides explicit guidelines on when to use full file content vs. search/replace blocks based on percentage_to_change (>50 vs <=50). It also includes a detailed example and rules for SEARCH/REPLACE blocks. However, it does not explicitly state when to avoid using this tool in favor of siblings.

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

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

The description adds behavioral context beyond annotations by detailing the initialization steps (setting workspace, reading files, configuring mode). It does not contradict the readOnlyHint=true annotation, as no destructive actions are mentioned. The description could mention if any session state is persisted.

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 and uses a bulleted list format that is easy to scan. Each sentence carries clear instructions. It could be slightly more organized by grouping related parameters, but overall it is efficient and front-loaded.

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

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

For a tool with 8 parameters, no output schema, and annotations, the description covers main usage scenarios but lacks information about what the agent receives or any side effects. It assumes prior knowledge of the wcgw shell tools. This is adequate but could be more 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 description adds meaning beyond the schema for key parameters like any_workspace_path, initial_files_to_read, mode_name, and allowed_globs. It explains default values and usage context. However, task_id_to_resume and thread_id are not elaborated, but schema coverage is high enough.

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 it is an initialization tool to be called at the start of the conversation before using shell tools. It specifies the resource (shell) and distinguishes from sibling tools by being a prerequisite.

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

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

The description provides explicit when-to-use guidelines for different call types (first_call, user_asked_mode_change, etc.) and explains when to set parameters like mode_name and allowed_globs. However, it does not explicitly say when not to use this tool or mention alternatives.

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

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

Annotations already mark the tool read-only and closed-world, so no further safety disclosure is needed. The description adds useful operational behavior: path expectations, line-range syntax, and thread_id sourcing. It does not cover error or return behavior, but this is a minor gap for a simple read tool.

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

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

Four tight bullet points lead with the core purpose, and the conditional line-range rule is clearly nested. There is no filler; every sentence contributes to correct invocation.

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

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

For a two-parameter, read-only tool with no output schema, the description is nearly complete: it covers paths, line ranges, and thread_id. It does not specify how multiple file contents are returned, but the simple nature of the tool makes the output inferable.

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 parameter meaning, and it does. It explains file_paths as absolute paths with optional range syntax and clarifies thread_id availability ('returned by Initialize', 'legacy clients may omit it'), adding real semantics 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?

Description opens with 'Read full file content of one or more files,' a specific verb-resource pair with clear scope (full content, multiple files). This distinguishes it from siblings such as FileWriteOrEdit, ReadImage, and BashCommand without needing to open 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?

Provides concrete guidance: absolute paths only with ~ allowed, line-range extraction only when line numbers are needed, and reuse of thread_id from Initialize. It does not explicitly state when not to use this tool or name alternatives, but the conditional usage is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description does not contradict them. The added note about thread_id and legacy clients is useful behavioral context beyond the structured fields, but the description does not disclose other behaviors such as error cases or what happens when the image cannot be read.

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 primary action is front-loaded, and the optional parameter guidance is placed in the second sentence where it belongs.

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 tool with minimal schema, the description covers the main input and the key optional parameter. Still, it lacks an explicit distinction from ReadFiles and does not mention what the tool returns, which would help an agent use it more reliably.

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 adds meaningful semantics for thread_id ('returned by Initialize... legacy clients may omit it'), but it says nothing about file_path beyond the schema's name and 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 states a clear action ('Read an image') and a resource/context ('from the shell'), so an agent can generally tell what the tool does. However, it does not explicitly distinguish ReadImage from the sibling ReadFiles, leaving some ambiguity about when the image-specific tool is preferred.

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 only guidance is about the thread_id parameter: use the one from Initialize when available, and legacy clients may omit it. There is no guidance about when to use ReadImage versus alternatives like ReadFiles or BashCommand, so tool-selection context is missing.

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