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

Beyond the annotations (destructiveHint=true), the description reveals that the command runs in a subprocess via the system shell, that pipes/redirections are supported, and that care is needed to avoid command injection. The return format is also disclosed. This adds meaningful behavioral context beyond the annotation flags.

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-organized with clear sections (introduction, caution, Args, Returns). It is moderately concise, though the Args section duplicates schema descriptions. The security warning and shell behavior details justify the length, and no filler is present.

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 (5 params, annotations, and an output schema), the description covers all key aspects: execution model, shell behavior, security considerations, and return format. It does not explicitly describe timeout side-effects beyond the 'timed_out' return key, but this is minor given the output schema exists.

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

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

The input schema already provides 100% description coverage for all five parameters, including defaults and constraints. The description's Args section largely repeats this information without adding significant new semantics. Baseline of 3 is appropriate because the schema does the heavy lifting.

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 clear verb+resource: 'Execute a terminal command and return stdout, stderr, and exit code.' It specifies the tool's scope as executing commands in a subprocess, which clearly differentiates it from sibling tools like agent_read_file or agent_web_search that handle files, memory, or web 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?

The description provides clear context for when to use the tool (running terminal commands) and includes a security caution about untrusted input. However, it does not explicitly name alternatives or state when not to use it, though the sibling tools are distinct enough that the intended usage is 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 declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond those flags by enumerating accepted skill file formats and specifying the JSON return structure with keys success, skills_dir, count, and skills.

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 well-organized: a one-sentence purpose, a bulleted list of skill types, and clearly labeled Args/Returns. Every sentence earns its place without redundant filler.

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

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

With only two optional parameters, a return shape already summarized, and rich annotation coverage, the description fully covers the tool's behavior, skill definitions, and expected output. The agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100% and the description's Args section primarily restates what the input schema already says (override skills_dir, optional glob pattern). The description adds no new parameter semantics beyond the schema, yielding the baseline score.

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 'Discover and list skills available in the configured skills directory', a specific verb+resource statement. It clearly distinguishes this discovery tool from siblings like agent_run_skill or agent_read_file by defining what counts as a skill.

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 tool's purpose is clear from 'Discover and list skills', and the sibling set reinforces when to use it (e.g., before running a skill with agent_run_skill). However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full usage 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 destructive and idempotent hints. The description adds value by specifying that a single entry is deleted and by disclosing the return format (JSON with 'success', 'key', and 'deleted' bool), providing more behavioral context than the annotations alone.

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 highly concise and well-structured: one clear purpose sentence followed by an Args/Returns breakdown. Every sentence contributes essential information, with no redundancy 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?

For a simple single-parameter destructive tool, the description is nearly complete: it states the action, the parameter, and the return format. The destructive hint in annotations covers the safety profile. It could be slightly more explicit about behavior on missing keys, but the 'deleted' bool in the return implies this.

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 covers the sole parameter 'key' with a description identical to that in the tool description (100% coverage). The description adds no new information about the parameter beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description starts with 'Delete a single memory entry by key', which is a specific verb+resource pair that clearly distinguishes this from siblings like save, load, list, and search. It unambiguously states the tool's function.

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 when to use this tool (to delete a specific memory entry) but provides no explicit guidance on when to choose this over alternatives, nor any exclusions or prerequisites. Usage is inferred from the verb and resource.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds behavioral context by specifying the return format ('JSON with keys success, count, entries') and the filtering behavior, going beyond what annotations 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 concise and well-structured: a one-sentence summary followed by a brief Args list and Returns line. Every sentence is relevant, and the format is immediately scannable.

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, the presence of an output schema, and thorough annotations, the description is complete. It communicates the core operation, optional filters, and return format, leaving no major gaps for an agent to make mistakes.

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 100%, with each parameter already described in the schema. The description's Args section repeats the same descriptions verbatim, adding no new meaning. The only additional context is the overall 'optionally filtered' phrase, which applies to the tool as a whole rather than individual 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 explicitly states 'List memory entries, optionally filtered by category and/or tag,' which is a specific verb+resource combination. This distinguishes it from sibling tools like agent_memory_search (which likely performs semantic search) and agent_memory_load (which loads a specific entry).

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 the tool is used for listing entries with optional filters, but it does not explicitly differentiate when to use this versus agent_memory_search or agent_memory_load. There is no mention of exclusions or alternative tools, so the guidance is only 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds the return format (JSON with 'success', 'key', and payload), which is useful. However, it does not mention behavior on missing keys or error conditions.

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-structured: a one-line purpose followed by Args and Returns sections. No wasted words.

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

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

With one simple parameter, full schema coverage, annotations, and a return description, the tool is sufficiently documented. The only gap is error behavior, but given the simplicity and presence of output schema, it is adequate.

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 fully covers the single 'key' parameter with a description identical to the tool description. No additional semantic meaning is provided beyond what the schema already has, so baseline 3 is appropriate.

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 loads a single memory entry by key, using a specific verb and resource. It distinguishes itself from sibling memory tools (save, list, delete, search) by focusing on loading one entry.

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 is given on when to use this tool versus alternatives like agent_memory_search or agent_memory_list. The description is minimal and leaves selection to the agent without mentioning exclusions or preferred use cases.

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 valuable behavioral context beyond annotations: storage in a JSON file, safe concurrent reads, and the overwrite parameter's failure condition. It also clarifies the operation type ('created' or 'updated'). This complements the idempotentHint and destructiveHint 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?

The description is well-structured with a clear opening purpose, a brief data model note, and labeled sections for Args and Returns. The 'Each entry stores' sentence is slightly redundant but harmless. It is concise enough while providing necessary 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?

With a full input schema, annotations, and an output schema, the description covers the core behavior, persistence model, parameter semantics, and return format. It explains the overwrite edge case and operation result. This is complete enough for an agent to invoke the tool correctly without needing additional context.

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

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

The input schema describes all five parameters with 100% coverage. The description's Args section essentially repeats the schema text without adding new meaning. Since schema coverage is high, the baseline of 3 applies, and the description doesn't elevate it further.

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 starts with a specific verb+resource+outcome: 'Persist a key/value memory entry to disk for cross-session recall.' This clearly differentiates it from sibling tools like load, search, or delete. The purpose is unmistakable and avoids ambiguity.

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 'for cross-session recall' implies the appropriate context for using this tool. It doesn't explicitly name alternatives or exclusions, but the sibling tool names (load, search, delete) make the complementary usage clear. The guidance is implicit but sufficient for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the return format (JSON with 'success', 'count', 'matches') and the search scope across key, value, and tags.

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 a leading sentence, Args, and Returns sections. The Args section is somewhat redundant with the schema, but the format is clean 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?

The description covers all essential aspects for a search tool: query semantics, parameter behavior, and return format. With an output schema present, return values need not be explained, yet they are, making the description 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 100%, so the schema already documents all parameters. The Args block in the description repeats the same information without adding extra meaning.

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

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

The description states a specific verb and resource: 'Search memory entries by substring or regex across key, value, and tags.' It clearly distinguishes from sibling tools like agent_memory_list and agent_memory_load.

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 (searching memory entries) without explicitly naming alternatives or exclusions. It is obvious that this is the search variant among the memory tools.

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 this as read-only and idempotent. The description adds valuable context: files are capped at MAX_FILE_SIZE, the tool returns a JSON object with specific keys, and offset/limit control line selection. This goes beyond simple safety hints.

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 sections for purpose, arguments, and returns. It is front-loaded with the primary action. While the Args section duplicates schema information, it is not overly verbose and every part serves a purpose, making it reasonably 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 output schema exists and annotations are present, the description covers essential behavioral details: MAX_FILE_SIZE cap, JSON return structure, and parameter semantics. It does not elaborate on error cases or exact MAX_FILE_SIZE value, but for a simple read tool this is sufficient and complete enough for 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?

The input schema already provides 100% coverage of all four parameters with descriptions. The description's 'Args' section largely repeats the schema, adding no new semantic information beyond what the schema already states. Baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states 'Read the contents of a text file' with a specific verb and resource. It also outlines the return format and key parameters (path, offset, limit, encoding), making it easy to distinguish from sibling tools like agent_write_file or agent_execute_command.

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 does not explicitly mention when to use this tool versus alternatives. Usage is implied by the name and description (reading text files), but there is no guidance on exclusions or when to prefer a different sibling tool, such as agent_execute_command.

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 annotations (readOnlyHint=false, destructiveHint=true), the description adds valuable details about execution mechanisms: Python skills run in-process, shell skills via subprocess, and markdown skills return file contents. It also discloses the return format and timeout behavior. It doesn't explicitly warn about side effects, but the destructive hint covers that, so the additional execution context earns a 4.

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 concise: a clear opening, a brief explanation of skill types, an Args list, and a Returns section. Every sentence contributes useful information without unnecessary fluff, making it easy for an agent to parse.

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 5 parameters, an output schema, and annotations, the description covers all necessary aspects: it explains the skill execution model, the meaning of each parameter (already in schema), and the return JSON structure. It also accounts for edge cases like timeout with the 'timed_out' key. There is no obvious missing information that would hinder 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 100%, so the schema already documents all parameters. The description's Args section largely repeats the schema descriptions (e.g., 'Primary input passed to the skill as the first argument' matches the schema exactly). It adds no new semantic nuance beyond what the schema provides, so the baseline 3 is appropriate.

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 'Invoke a discovered skill by name and return its result', which is a specific verb+resource pair that clearly identifies the tool's function. It also differentiates from sibling tools by focusing on skills rather than commands, files, memory, or web 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 clear context on when to use the tool: when a skill is discovered. It explains the three skill types and their execution methods, which helps the agent understand what will happen. However, it does not explicitly state alternatives or exclusion criteria, such as 'For raw shell commands, use agent_execute_command', so it stops short of a full 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by disclosing the supported engines, the return format (JSON string with keys), and the lack of API key requirement. This goes beyond the annotations, though it does not cover rate limits or failure behavior.

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

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

The description is well-structured with clear sections: engine list, result format, args, and returns. Every sentence provides useful information without redundancy or fluff.

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 is complete for a web search tool: it lists all parameters, supported engines, result structure, and output format. The output schema further clarifies returns, and the description aligns with it. No missing essential context.

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

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

The input schema already provides 100% coverage of parameter descriptions, including examples for region. The description's Args section largely mirrors the schema without adding meaningful new semantics, so the baseline 3 is appropriate.

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 searches the web and returns results, with a specific verb ('Search'), resource ('web'), and explicit support for multiple engines. This distinguishes it from sibling tools like file/memory/command 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 implies usage context ('Search the web') and mentions that no API key is required, which is helpful. However, it does not explicitly state when to prefer this over alternatives or when not to use it, though such guidance is not critical given the distinct purpose.

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 discloses key behavioral traits: append vs. overwrite behavior, optional parent directory creation, and the return format (JSON string with success, path, bytes_written, operation). These add value beyond the annotations (which already mark the tool as destructive and not read-only). There is no contradiction with 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 main action and structured with Args/Returns sections, which aids readability. However, the Args block duplicates the schema's parameter descriptions verbatim, adding redundancy. While not overly long, the repetition prevents a higher 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?

The description is quite complete for a file-writing tool. It covers the operation, parameters, defaults, and return value. An output schema exists, so return data is further specified. Missing elements like error handling or permissions are not critical for this context. The main gap is the lack of usage guidance, but that is already scored under dimension 2.

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 100%, so the schema already documents all five parameters. The description's Args section largely repeats this information (parameter names, defaults, and brief explanations) without adding new semantic detail. Thus, it earns the baseline score of 3.

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 function: 'Write text content to a file, optionally creating parent directories.' This is a specific verb+resource combination that distinguishes it from sibling tools like reading, executing commands, or memory 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 no guidance on when to use this tool versus alternatives. It does not mention scenarios where file writing is preferable to other operations, nor does it mention any exclusions or prerequisites. The only implied usage is 'writing text to files,' but no explicit context or alternative comparisons are given.

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