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

With no annotations provided, the description carries the full burden and adds valuable behavioral context: it explains that the tool can create nested directories, works only within allowed directories, normalizes paths automatically, and has path reliability considerations (absolute vs. relative/tilde). This goes beyond basic purpose to describe operational traits.

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 core purpose but includes verbose path instructions and meta-commentary about command referencing ('DC: ...'), which adds clutter. Some sentences (e.g., the referencing note) don't earn their place for tool selection, reducing efficiency.

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 no annotations, 0% schema coverage, and no output schema, the description does a solid job covering key aspects: purpose, behavioral constraints (allowed directories, path handling), and parameter guidance. It lacks details on error cases or return values, but for a single-parameter tool, it's reasonably 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 0% description coverage for its single parameter 'path', but the description compensates well by explaining path semantics: it must be absolute for reliability, is automatically normalized, and relative/tilde paths may fail. This adds meaningful context beyond the bare schema type 'string'.

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's purpose: 'Create a new directory or ensure a directory exists.' It specifies the verb ('create'/'ensure') and resource ('directory'), though it doesn't explicitly differentiate from siblings like 'list_directory' or 'move_file'. The mention of creating nested directories adds specificity.

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 implied usage guidance by stating 'Only works within allowed directories' and emphasizing absolute paths for reliability. However, it doesn't explicitly say when to use this tool versus alternatives (e.g., vs. 'move_file' for directory manipulation) or list any exclusions, leaving some context gaps.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so comprehensively. It explains the default behavior (replaces only ONE occurrence), how to replace multiple occurrences, the uniqueness requirement for context, what happens with non-exact matches (character-level diff shown), line limit warnings similar to write_file, and path handling requirements. This provides rich behavioral context beyond basic parameter documentation.

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 with clear sections and front-loaded information, but could be slightly more concise. The core purpose is stated immediately, followed by best practices, parameter explanations, behavioral details, and important notes. While every sentence adds value, some redundancy exists (e.g., path guidance appears in multiple places). Overall, it's efficiently organized but not maximally concise.

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 (file editing with precise text replacement), lack of annotations, and no output schema, the description provides complete contextual information. It covers purpose, usage guidelines, all parameters, behavioral characteristics, error conditions, best practices, and even references to related tools. This gives the AI agent everything needed to select and invoke this tool correctly for surgical text replacements.

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 fully compensates by explaining all parameters in detail. It clearly defines file_path, old_string, new_string, and expected_replacements with their meanings, default values, and usage implications. The description adds significant value beyond the bare schema by explaining how these parameters interact (e.g., how expected_replacements affects the replacement behavior) and providing practical guidance on their use.

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's purpose: 'Apply surgical text replacements to files.' This is a specific verb ('apply surgical text replacements') + resource ('files') combination that distinguishes it from sibling tools like write_file (which creates/overwrites entire files) or read_file (which only reads). The description effectively communicates this is for targeted modifications rather than wholesale 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?

The description provides explicit guidance on when to use this tool versus alternatives. It states: 'When editing multiple sections, make separate edit_block calls for each distinct change rather than one large replacement' and references write_file as a similar tool with line limit warnings. It also gives clear 'BEST PRACTICE' recommendations for making small, focused edits and distinguishes this from broader file operations available in the sibling toolset.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states 'force terminate' which implies a destructive action, but doesn't clarify permissions needed, side effects, error conditions, or what 'force' entails compared to regular termination. This leaves significant behavioral gaps.

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

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

The description is reasonably concise with two sentences, but the second sentence about 'Desktop Commander' terminology adds minimal value for tool selection. The structure is front-loaded with the core purpose, but could be more focused.

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 operation with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It doesn't explain the parameter, behavioral implications, success/failure conditions, or what distinguishes it from similar sibling tools.

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 for the undocumented 'pid' parameter. The description provides no information about what 'pid' represents, its format, or valid values. This leaves the single required parameter completely unexplained.

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 ('force terminate') and target ('a running terminal session'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'kill_process' or 'interact_with_process', which might have overlapping functionality.

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 no guidance on when to use this tool versus alternatives like 'kill_process' or 'interact_with_process'. The second sentence references 'Desktop Commander' terminology but doesn't offer practical usage context or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool returns (server configuration as JSON with specific fields) but does not mention potential side effects, permissions required, rate limits, or error conditions. It adds value by detailing the configuration structure but lacks comprehensive behavioral context.

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 core purpose ('Get the complete server configuration as JSON'), followed by a bulleted list of included fields and a note on referencing. The bulleted list is efficient for detailing fields, but the referencing note could be more concise. Overall, it is well-structured with minimal waste.

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

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

Given no annotations and no output schema, the description provides good detail on the configuration fields returned, which helps compensate. However, it lacks information on return format (e.g., JSON structure depth), error handling, or operational constraints. For a read-only tool with rich output, this is adequate but has gaps in completeness.

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 0 parameters with 100% coverage, so no parameter information is needed. The description appropriately does not discuss parameters, focusing instead on the output content. This meets the baseline of 4 for tools with no parameters, as it avoids unnecessary repetition.

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 specific action ('Get') and resource ('complete server configuration as JSON'), distinguishing it from siblings like 'get_file_info' or 'get_usage_stats'. It explicitly lists the configuration fields included, making the purpose unambiguous and specific.

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

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

The description implies usage by mentioning it can be referenced as 'DC: ...' or 'use Desktop Commander to ...', but it does not explicitly state when to use this tool versus alternatives like 'get_file_info' or 'set_config_value'. No exclusions or prerequisites are provided, leaving usage context inferred 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?

With no annotations provided, the description carries the full burden. It discloses important behavioral traits: path normalization, absolute vs relative path reliability, tilde path limitations, and directory restrictions. It doesn't mention error handling or performance characteristics, but covers key operational constraints.

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 appropriately sized and front-loaded with the core purpose. The bulleted list efficiently conveys what metadata is returned. The path guidance is necessary but could be slightly more concise. The DC reference at the end feels slightly extraneous but doesn't significantly detract.

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 single-parameter read operation with no annotations and no output schema, the description is quite complete. It explains what metadata is returned, path requirements, and operational constraints. The main gap is lack of explicit mention of error conditions or return format, but given the tool's relative simplicity, it's reasonably comprehensive.

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 for the single 'path' parameter, the description compensates well by explaining path requirements: must be absolute for reliability, paths are normalized, relative paths may fail, tilde paths might not work. This adds crucial semantic context 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 clearly states the verb 'retrieve' and resource 'detailed metadata about a file or directory', with specific examples of what metadata is included. It distinguishes from siblings like list_directory (which lists contents) and read_file (which reads 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?

The description provides explicit guidance on when to use this tool: 'Only works within allowed directories' and 'Always use absolute paths for reliability'. It also distinguishes from alternatives by specifying it retrieves metadata, not content or listings.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns summary data (usage, success/failure rates, performance metrics), which is helpful, but doesn't cover important aspects like whether this requires special permissions, has rate limits, affects system state, or what format the return data takes. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

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

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

The description is three sentences with some wasted space (extra line breaks and quotation marks in the provided text). The first two sentences are useful, but the third sentence about referencing commands adds little value for an AI agent selecting tools. It's moderately concise but could be more focused.

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 has 0 parameters, no output schema, and no annotations, the description provides basic information about what the tool does and returns. However, it lacks details about the return format, error conditions, or prerequisites that would be helpful for a debugging/analysis tool. It's minimally adequate but has clear gaps in completeness.

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 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, which is correct for a parameterless tool. It adds value by explaining what the tool returns rather than focusing on inputs.

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 the tool 'Get usage statistics for debugging and analysis', which provides a clear verb ('Get') and resource ('usage statistics') with a purpose ('debugging and analysis'). However, it doesn't differentiate from sibling tools like 'get_config' or 'get_file_info' that also retrieve information, making the purpose somewhat generic rather than specific.

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

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

The description includes no guidance on when to use this tool versus alternatives. It mentions the tool can be referenced in instructions, but this doesn't help an AI agent decide when this tool is appropriate compared to other get_* tools on the server. There's no explicit when/when-not or alternative tool recommendations.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly explains that the tool opens a browser form, describes what data is automatically pre-filled (usage statistics, platform, client_id), and outlines the user's manual input requirements. However, it doesn't mention potential side effects like browser pop-up behavior or error handling.

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 core purpose but includes extensive details about pre-filled data and survey questions that could be condensed. While informative, some sections like the example interaction and referencing instructions feel somewhat redundant given the clear workflow 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?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is largely complete. It explains the tool's behavior, workflow, and user interaction context. However, it lacks technical details like browser requirements or error scenarios that could be relevant for an AI agent.

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 0 parameters with 100% coverage, so the baseline is 4. The description reinforces this by stating 'No parameters are needed - just call the tool to open the form,' which adds clarity beyond the empty 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 explicitly states the tool's purpose: 'Open feedback form in browser to provide feedback about Desktop Commander.' It uses specific verbs ('open', 'provide feedback') and clearly distinguishes this from sibling tools like get_usage_stats or set_config_value by focusing on user feedback collection rather than system 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?

The description provides explicit guidance on when to use this tool: 'When user agrees to give feedback, just call this tool immediately' and 'No need to ask questions or collect information.' It also distinguishes this from tools that might pre-fill data by stating 'no pre-filling available' and clarifies the workflow steps.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses prompt-waiting, error detection, early exit, output cleanup, and parameter defaults, but it omits the security and destructive implications of executing arbitrary code in a live process as well as process lifecycle risks.

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 heavily repetitive, with multiple all-caps warnings restating the same file-analysis rule. Important workflow information is present but buried in redundant sections, so many sentences do not earn their 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 description supplies a workflow and parameter defaults for a tool with no annotations and no output schema. However, it omits process lifecycle details, expected failure modes, and security warnings, and it does not explain how this tool relates to read_process_output or other process-management siblings.

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 does list all four parameters and adds meaning beyond the schema, including that pid comes from start_process, that input is code/command text, and the defaults for timeout_ms and wait_for_prompt.

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 opening sentence states a specific verb and resource: 'Send input to a running process and automatically receive the response.' It also names start_process in the workflow, though it does not clearly differentiate from siblings like read_process_output. The core purpose is clear despite heavy tangential file-analysis guidance.

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 usage direction, including a priority order and the instruction to use start_process + interact_with_process for local file analysis. It names alternatives such as command-line tools and the analysis tool, but the guidance is overbroad and does not mention the sibling read_process_output.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the destructive nature ('forcefully terminate') and includes a caution warning, which are essential behavioral traits. However, it doesn't mention potential side effects, error conditions, permission requirements, or what happens if the PID doesn't exist.

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 first two sentences are well-structured and front-loaded with essential information. However, the third sentence about command referencing adds unnecessary length without improving tool understanding, reducing overall conciseness.

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

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

For a destructive tool with no annotations and no output schema, the description provides adequate basic information about purpose and caution. However, it lacks details about return values, error handling, system impacts, and doesn't fully compensate for the missing structured documentation.

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 schema has 0% description coverage for its single parameter (pid), but the description adds meaningful context by specifying that it terminates 'a running process by PID'. This clarifies what the pid parameter represents and how it's used, though it doesn't provide format details or validation rules.

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 specific action ('terminate') and target resource ('a running process by PID'), distinguishing it from sibling tools like 'interact_with_process' or 'start_process'. It uses precise technical language that leaves 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 provides clear context with 'Use with caution as this will forcefully terminate the specified process', which implicitly suggests when to use it (for forceful termination) and hints at alternatives (less forceful methods). However, it doesn't explicitly name alternative tools or specify exact scenarios when not to use it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it distinguishes files and directories with prefixes, works only within allowed directories, and handles path normalization. However, it lacks details on error handling or performance aspects like rate limits, keeping it from a perfect score.

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 appropriately sized and front-loaded, starting with the core purpose. However, it includes minor redundancy in path advice and an unrelated note about referencing as 'DC:' or 'Desktop Commander,' which slightly reduces efficiency without adding critical 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?

Given the tool's moderate complexity (one parameter, no output schema, no annotations), the description is largely complete, covering purpose, usage, behavior, and parameters. It could improve by detailing output format or error cases, but it provides sufficient context for effective use in most scenarios.

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 0% description coverage for the single parameter 'path,' but the description compensates fully by explaining its semantics: it must be a specified path, with detailed guidance on using absolute paths, normalization, and avoiding relative or tilde paths. This adds significant meaning beyond the basic 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 clearly states the verb ('Get a detailed listing') and resource ('all files and directories in a specified path'), making the purpose specific. It distinguishes from sibling tools like 'execute_command' by explicitly stating to use this instead for ls/dir commands, ensuring it stands out in the context of the server.

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 guidance on when to use this tool ('Use this instead of 'execute_command' with ls/dir commands') and includes alternatives, such as avoiding relative paths in favor of absolute ones. It also specifies exclusions like 'Only works within allowed directories,' offering clear context for proper usage.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the return format (process information including PID, command name, CPU usage, and memory usage), which is helpful. However, it lacks details on potential limitations such as performance impact, real-time vs. cached data, or system-specific variations, which are important for a tool that lists system processes.

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 core functionality in the first sentence, followed by return details and a contextual note. The sentences are relevant, but the third sentence about referencing 'DC' or 'Desktop Commander' is somewhat extraneous and could be omitted without losing clarity, slightly reducing efficiency.

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 (listing system processes) and lack of annotations or output schema, the description provides basic return information but misses behavioral context like error handling, permissions required, or data freshness. It is adequate for a simple list operation but could be more complete for a system-level 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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, which is efficient. A baseline of 4 is applied since there are no parameters to document, and the description does not add unnecessary information.

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 verb 'List' and the resource 'all running processes', which is specific and unambiguous. It distinguishes itself from sibling tools like 'interact_with_process', 'kill_process', and 'read_process_output' by focusing solely on listing rather than modifying or interacting with processes.

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 implies usage context by specifying 'all running processes', which suggests it should be used when a comprehensive overview is needed. However, it does not explicitly state when to use this tool versus alternatives like 'get_usage_stats' or 'list_sessions', nor does it provide exclusions or prerequisites for usage.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it lists active sessions, shows status details (PID, Blocked, Runtime), and provides debugging insights (e.g., blocked status indicates waiting for input, long runtime may indicate stuck processes). This adds valuable context beyond basic functionality, though it could mention potential limitations like rate limits or permissions.

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 structured with clear sections (purpose, status details, debugging tips, usage notes), but it includes some verbose or redundant elements, such as the debugging REPLs section repeating similar points and the final sentence about referencing commands, which may not be essential. It could be more streamlined while retaining key 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?

Given the tool's complexity (simple list operation with 0 parameters, no annotations, no output schema), the description is mostly complete. It explains what the tool does, what information it provides, and how to use it for debugging. However, it lacks details on output format (e.g., structure of returned data) and any error conditions, which would enhance completeness for an agent.

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 0 parameters with 100% coverage, so no parameter information is needed. The description appropriately focuses on output semantics and usage, adding value by explaining what the tool returns and how to interpret it, which compensates for the lack of an output 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 clearly states the specific action ('List all active terminal sessions') and resource ('terminal sessions'), distinguishing it from siblings like list_directory or list_processes. It provides concrete details about what information is shown (PID, Blocked status, Runtime), making the purpose unambiguous and specific.

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

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

The description includes explicit usage guidance for debugging REPLs (e.g., 'Use this to verify sessions are running before sending input'), which helps clarify when to use this tool. However, it does not explicitly mention when NOT to use it or name specific alternatives among siblings, such as list_processes, which might be relevant for broader process monitoring.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the tool can move or rename in one operation, both source and destination must be within allowed directories, and it requires absolute paths for reliability. It also mentions path normalization and limitations with relative/tilde paths. However, it lacks details on error handling or permissions.

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 appropriately sized and front-loaded, starting with the core purpose. Most sentences add value, such as operational details and path guidelines. However, the final sentence about referencing as 'DC:' is slightly extraneous and could be trimmed for better conciseness.

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

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

Given no annotations and no output schema, the description does a good job covering the tool's purpose, usage, and parameters. It addresses key contextual aspects like path requirements and operational scope. However, it lacks details on return values, error conditions, or side effects, which would enhance completeness for a 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?

The input schema has 0% description coverage, so the description must compensate. It adds significant meaning: 'source' and 'destination' are clarified as paths for files/directories, with constraints like requiring absolute paths and being within allowed directories. It also explains that the operation handles both moving and renaming. This goes well beyond the bare schema, though it could specify path formats more precisely.

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 verb ('move or rename') and resource ('files and directories'), and distinguishes from siblings like 'create_directory' (creation), 'read_file' (reading), and 'write_file' (writing). It specifies the operation can handle both moving between directories and renaming in one action.

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 explicitly states when to use this tool: for moving or renaming files/directories. It provides clear alternatives by naming sibling tools for different operations (e.g., 'create_directory' for creation, 'read_file' for reading). It also includes usage notes about path requirements, making it highly actionable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so comprehensively. It details performance optimizations (reverse reading, byte estimation, streaming), constraints (allowed directories, URL reading limitations), file type handling (text vs images), path requirements (absolute vs relative), and operational specifics like how offset/length parameters interact. This provides rich behavioral context beyond basic functionality.

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 with clear sections (purpose, preference guidance, parameter details, examples, performance, constraints, file handling, path instructions). While comprehensive, some sentences could be more concise (e.g., the final paragraph about referencing could be trimmed). However, most content earns its place by providing essential operational context.

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 complexity of the tool (4 parameters, no annotations, no output schema), the description is remarkably complete. It covers purpose, usage guidelines, parameter semantics, behavioral traits, performance characteristics, constraints, file type handling, and practical implementation details. For a read operation with rich parameter interactions, this provides sufficient context for an agent to use 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?

With 0% schema description coverage, the description fully compensates by providing detailed semantics for all parameters. It explains 'offset' with positive/negative behavior and 0-based indexing, 'length' with default values and interaction rules, 'path' with absolute path requirements, and 'isUrl' with URL-specific behavior. The examples concretely illustrate parameter usage, adding significant 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 explicitly states the tool's purpose: 'Read the contents of a file from the file system or a URL with optional offset and length parameters.' It distinguishes from sibling tools like 'read_multiple_files' by focusing on single-file reading and from 'execute_command' by recommending preference over cat/type commands. The verb+resource combination is specific and clear.

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 guidance on when to use this tool: 'Prefer this over 'execute_command' with cat/type for viewing files.' It also mentions when not to use it (for relative paths unless explicitly requested) and distinguishes it from sibling tools like 'read_multiple_files' by focusing on single-file operations. The context of file system vs URL reading is clearly delineated.

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

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

With no annotations provided, the description carries full burden and discloses key behaviors: handles text and image files (PNG, JPEG, GIF, WebP), continues on individual file failures, works within allowed directories, and requires absolute paths for reliability. It doesn't cover rate limits or auth needs but provides substantial operational context.

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?

Well-structured with clear sections: purpose, return format, file handling, error behavior, directory constraints, and path instructions. Some redundancy in path advice slightly reduces efficiency, but overall front-loaded and informative.

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 no annotations and no output schema, the description provides good coverage: explains what the tool does, how to use it, behavioral traits, and parameter semantics. It could detail output format more explicitly but is largely complete for a read operation 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% with 1 parameter ('paths'), and the description compensates by explaining that 'paths' should be absolute for reliability, automatically normalized, and that relative/tilde paths may fail. It adds meaning beyond the bare schema type definition.

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 verb ('read') and resource ('multiple files simultaneously'), distinguishing it from sibling 'read_file' which handles single files. It specifies the scope of reading multiple files at once with content returned by 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?

Explicitly states when to use this tool ('read multiple files simultaneously') and provides alternatives: it distinguishes from 'read_file' for single files, mentions 'only works within allowed directories' as a constraint, and references 'Desktop Commander' context for usage.

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

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

With no annotations provided, the description carries full burden and does well by detailing behavioral traits: early exit on REPL prompts, detection of completion vs running states, prevention of hanging, and clear status messages. It explains what the tool does beyond basic reading, though it could mention error handling or output format.

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 overly verbose and poorly structured, with redundant sections (e.g., 'SMART FEATURES' and 'REPL USAGE' overlap), bullet points that could be condensed, and unnecessary marketing language ('This command can be referenced as...'). It lacks front-loading of critical 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?

Given no annotations, no output schema, and low schema coverage, the description is moderately complete. It covers behavioral aspects well but misses parameter details and return value explanation. For a tool with smart detection features, it's adequate but has gaps in technical specifics.

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 for the two parameters (pid, timeout_ms). It mentions 'timeout' briefly but doesn't explain what pid represents, the units for timeout_ms, or default behaviors. The description adds minimal 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 clearly states the tool reads output from a running process with intelligent completion detection, which is a specific verb+resource combination. It distinguishes from siblings like 'interact_with_process' by focusing on reading output rather than sending input, though the distinction could be more explicit.

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 clear context for when to use this tool: when a process is running and output needs to be read with smart detection. It implies an alternative ('interact_with_process' for when the process is waiting for input) but doesn't explicitly name it or provide exclusion criteria.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: default timeout (30 seconds), search constraints (only within allowed directories), path handling requirements (absolute paths recommended), and performance characteristics (fast and powerful). It doesn't mention error handling or output format details, but covers most critical operational aspects.

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 appropriately sized and front-loaded with the core purpose. Each paragraph adds value: purpose, usage guidelines, capabilities, operational constraints, and path guidance. The final sentence about 'DC: ...' references could be trimmed as it's more about external documentation than tool functionality, but overall the structure is efficient.

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

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

Given the tool's complexity (8 parameters, no annotations, no output schema), the description provides substantial context about what the tool does, when to use it, key behaviors, and parameter guidance. It doesn't describe the return format or error conditions, but covers most aspects needed for effective use. The sibling tool differentiation and path guidance are particularly valuable.

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 for 8 parameters, the description compensates well by explaining several parameter semantics: it mentions 'regular expressions' (relates to pattern parameter), 'file pattern filtering' (relates to filePattern), 'context lines' (relates to contextLines), and 'timeout' customization (relates to timeoutMs). It also provides crucial guidance about the 'path' parameter requiring absolute paths. However, it doesn't cover all 8 parameters.

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's purpose: 'Search for text/code patterns within file contents using ripgrep.' It specifies both the verb ('search') and resource ('text/code patterns within file contents'), and distinguishes it from sibling tools like 'search_files' by emphasizing content search versus file metadata search.

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 guidance on when to use this tool versus alternatives: 'Use this instead of 'execute_command' with grep/find for searching code content.' It also mentions 'Fast and powerful search similar to VS Code search functionality,' helping the agent understand appropriate contexts for its use.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: case-insensitive substring matching, recursive search through subdirectories, a default 30-second timeout (customizable via timeoutMs), restriction to allowed directories, and path normalization. It also notes reliability issues with relative and tilde paths. However, it lacks details on output format or error handling, which could be useful for an agent.

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 appropriately sized but not optimally structured. Key information is front-loaded (purpose and basic usage), but it includes verbose path advice and a tangential note about command referencing ('DC: ...') that doesn't add core value. Some sentences could be trimmed for better focus without losing essential details.

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 parameters, no annotations, no output schema), the description is largely complete. It covers purpose, usage, behavioral traits, and parameter semantics well. However, it lacks information on the return value (e.g., what the search results look like) and error conditions, which are important for an agent to handle responses appropriately.

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 adds meaningful semantics for all parameters: 'path' is explained with detailed guidance on absolute vs. relative paths and normalization; 'pattern' is implied as the substring for matching; 'timeoutMs' is described as customizing the default 30-second timeout. This goes beyond the bare schema, though it could explicitly map each parameter name to its purpose.

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's purpose with specific verbs ('finds files by name') and resource ('files'), and distinguishes it from sibling tools by explicitly contrasting it with 'execute_command' and 'search_code' (implied). It provides detailed matching behavior ('case-insensitive substring matching') and search scope ('through all subdirectories from the starting 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 description explicitly states when to use this tool ('Use this instead of 'execute_command' with find/dir/ls for locating files') and provides clear context on path handling ('Always use absolute paths for reliability'). It also mentions constraints like 'Only searches within allowed directories' and timeout customization, offering practical guidance for effective use.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by including a WARNING about security implications and important notes about the 'allowedDirectories' parameter behavior. It also mentions the tool can be referenced as 'DC: ...' which provides implementation context. However, it doesn't cover error conditions, validation rules, or what happens when invalid keys/values are provided.

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 appropriately sized but not optimally structured. The core purpose is clear in the first sentence, but the WARNING and IMPORTANT sections are buried in the middle rather than front-loaded. The final sentence about referencing as 'DC: ...' feels somewhat out of place and doesn't add critical value for tool selection.

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 this is a mutation tool with no annotations and no output schema, the description does quite well. It covers the purpose, security implications, parameter details, and specific behavioral notes. The main gap is the lack of information about return values or error responses, which would be important for a configuration-setting 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 and 2 parameters, the description compensates excellently. It provides a comprehensive list of config keys with their expected data types and specific behavioral notes (like the empty array behavior for allowedDirectories). This adds substantial meaning beyond what the bare schema provides, fully documenting the parameter semantics.

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's purpose: 'Set a specific configuration value by key.' This is a specific verb+resource combination (set + configuration value). However, it doesn't explicitly distinguish from its sibling 'get_config' beyond the obvious set vs. get difference, missing an opportunity for clearer sibling differentiation.

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

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

The description provides clear context about when to use this tool: 'Should be used in a separate chat from file operations and command execution to prevent security issues.' This gives important operational guidance. However, it doesn't explicitly mention when NOT to use it or provide alternatives to setting configuration values.

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?

Since no annotations are provided, the description bears the full burden. It provides rich behavioral context beyond simple execution, detailing the environment (Linux/bash), specific detection methods (REPL prompts, waiting for input), and recognized process states.

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 sheer volume of highly detailed instructions, workflows, and 'critical rules' makes the definition extremely verbose. While every sentence serves a necessary purpose due to the tool's complexity and lack of structured metadata, the overall length prevents a perfect score for conciseness.

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

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

Given the complexity of managing terminal processes, this definition is highly complete. It covers OS-specific notes, path reliability concerns, state detection, and the required sequential usage of related sibling tools like `interact_with_process` and `read_process_output`.

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 fully compensate. It defines the `command` parameter using extensive, syntactically correct examples across multiple contexts (Python REPL, Node.js, Unix pipe commands), making parameter use unambiguous.

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 is extremely clear, stating that this is the 'PRIMARY TOOL FOR FILE ANALYSIS AND DATA PROCESSING.' It distinguishes itself explicitly from the 'analysis tool,' preventing agents from misselecting the browser-based tool for local file tasks.

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 provides definitive rules ('CRITICAL RULE: ...NEVER use analysis/REPL tool') and comprehensive instructions on when and how to use it, detailing required workflows for local file processing (e.g., using absolute paths and sequential interaction with interact_with_process).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so comprehensively. It explains performance characteristics (files over 50 lines generate performance notes), constraints (only works within allowed directories), path handling (absolute vs. relative paths), continuation behavior for incomplete operations, and chunking requirements. This provides rich behavioral context beyond basic functionality.

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?

While the description is well-structured with clear sections and bullet points, it is quite lengthy with multiple repetitions about chunking and path handling. Some information (like the 'DC: ...' reference) seems less essential. The description could be more concise while retaining its comprehensive 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?

Given the tool's complexity (file writing with performance considerations), lack of annotations, and no output schema, the description provides complete contextual information. It covers purpose, usage patterns, behavioral constraints, parameter semantics, error handling, and performance considerations. Nothing essential appears to be missing for effective tool use.

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 for 3 parameters, the description must and does compensate by providing extensive parameter semantics. It explains the 'mode' parameter values ('rewrite' vs 'append') with concrete usage examples, clarifies 'path' parameter requirements (absolute paths for reliability), and implicitly describes 'content' parameter usage through chunking guidelines. This adds significant meaning 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 explicitly states the tool's purpose as 'Write or append to file contents', which is a specific verb+resource combination. It clearly distinguishes this from sibling tools like read_file, edit_block, and move_file by focusing on writing/creating file content rather than reading, editing specific blocks, or moving files.

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

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

The description provides extensive guidance on when and how to use this tool, including explicit instructions for chunking ('Always write files in chunks of 25-30 lines maximum'), a step-by-step process for writing files, and specific scenarios when chunking should be used. It also contrasts with implied alternatives by emphasizing this is the 'normal, recommended way' rather than emergency measures.

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