Server Quality Checklist

Tool Scores

• todowriteB
  3.4/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the full burden. It mentions session scoping but does not disclose whether the tool replaces the entire list or merges, whether it is destructive, or what the return value is. For a write tool, these are significant gaps.

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

  Conciseness4/5

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

  The description is short and front-loaded with the action. The first sentence is essential, but the second sentence merely restates what the schema already says, making it somewhat redundant. Overall, it is concise and easy to parse.

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

  Completeness3/5

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

  For a simple tool with a single parameter and no output schema, the description provides the core purpose and item structure. However, it lacks clarity on how the list is maintained (whether the whole list is replaced or merged), which is important for correct usage. It is minimally complete but has gaps.

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

  Parameters3/5

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

  The schema fully documents the 'todos' parameter with descriptions for content, status, and priority (100% coverage). The description only repeats that items have content, status, and priority, adding no additional semantics or examples beyond the schema.

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

  Purpose5/5

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

  The description clearly states a specific verb ('Create and maintain') and a specific resource ('structured task list for the current MCP session'). It distinguishes the tool from all siblings, which are unrelated (file ops, shell, web). This fully clarifies 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.

  Usage Guidelines3/5

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

  The description implies usage for managing a session-scoped todo list, but does not explicitly state when to use it versus alternatives or when not to use it. Since sibling tools are unrelated, there is low ambiguity, but explicit guidance is absent.

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

• websearchA
  3.5/5.0
  Behavior2/5

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

  With no annotations provided, the description must carry the burden of behavioral disclosure. It does not describe the return format, whether results include content or just URLs, rate limits, or how provider controls affect behavior. For a web search tool, this leaves important operational details undisclosed.

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

  Conciseness5/5

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

  The description is a single well-structured sentence that front-loads the core purpose, then lists required vs. optional parameters. No word is wasted, and it is easy to scan.

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

  Completeness2/5

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

  Given there is no output schema and no annotations, the description should explain what the tool returns and how the optional controls affect behavior. It only covers the basic invocation pattern, leaving significant gaps for an agent deciding whether and how to use the tool.

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

  Parameters2/5

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

  Schema coverage is 60%, and the description only groups parameters as 'optional provider controls' without explaining their semantics. The enums for 'type' and 'livecrawl' are particularly ambiguous, and the description does not clarify what values like 'fast' or 'preferred' mean. It adds little beyond the schema's terse field descriptions.

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

  Purpose5/5

  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 the web through the configured Exa or Parallel provider.' This is a specific verb+resource pairing that distinguishes websearch from sibling tools like webfetch, which likely fetches a specific URL.

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

  Usage Guidelines4/5

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

  The description provides clear context for using the tool ('Search the web') and states that query is required while listing optional parameters. However, it does not explicitly mention when to use websearch over webfetch or other alternatives, so it lacks explicit exclusions.

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

• bashA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does reveal that 'Output is capped; complete truncated output is saved to a file,' which is useful. But it does not mention exit codes, error handling, or potential side effects of running arbitrary commands, leaving some gaps.

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

  Conciseness5/5

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

  The description is three concise sentences, each earning its place: purpose, usage guidance, and a behavioral note. No wasted words or repetition of schema details.

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

  Completeness3/5

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

  For a simple tool with no output schema and straightforward parameters, the description covers key points: execution, timeout units, and output handling. However, it omits details about command compatibility (e.g., shell used) or error behavior, which could be relevant but are not strictly required given the simple schema.

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

  Parameters3/5

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

  The schema description coverage is 100% since all parameters have descriptions. The tool description adds a bit of value by reinforcing the unit for timeout and advising against 'cd' commands, but these are largely redundant with schema text. The additional guidance on workdir is helpful but not enough to exceed the baseline of 3.

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

  Purpose5/5

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

  The description clearly states 'Execute a shell command' with a specific verb and resource. It is unambiguous and distinguishes this tool from siblings like file operations or web searches which have different purposes.

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

  Usage Guidelines4/5

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

  The description gives clear practical guidance: 'Set workdir instead of changing directories inside the command when possible' and specifies that timeout is in milliseconds. However, it does not explicitly discuss when to prefer bash over sibling tools or exclude scenarios, though the context implies bash is for running shell commands.

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

• editA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It explains OpenCode matching semantics, the need to preserve indentation, the failure condition when oldString is ambiguous, and the replaceAll fallback. This is substantial behavioral information, though it does not cover permissions or side effects of the edit operation.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the core purpose, and every sentence earns its place. It is concise, structured, and free of fluff.

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

  Completeness4/5

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

  For a file-edit tool with no annotations and no output schema, the description covers the essential behavior: matching semantics, indentation handling, failure conditions, and disambiguation. It does not mention return values or when to prefer this over apply_patch/write, but it is adequate for typical use.

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

  Parameters3/5

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

  The input schema provides descriptions for all four parameters, giving 100% schema coverage. The description adds a bit of context by noting the matching semantics (which impacts oldString) and the replaceAll fallback, but it does not significantly enhance the parameter-level understanding beyond the schema.

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

  Purpose4/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Replace text in a file using OpenCode matching semantics.' This makes the purpose clear, but it does not explicitly differentiate from sibling tools like apply_patch or write, so it lacks the full points for sibling differentiation.

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

  Usage Guidelines4/5

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

  The description provides concrete usage guidance: 'Preserve the exact indentation from read output, excluding its line-number prefix' and explains how to handle ambiguity: 'supply more context or use replaceAll to replace every occurrence.' This gives clear context on successful operation, though it does not mention when to use this tool versus alternatives like apply_patch or write.

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

• globA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It states the tool is 'Fast' and 'Returns matching file paths,' implying a read-only search. But it doesn't disclose edge-case behaviors like hidden file handling, case sensitivity, or behavior on unmatched patterns. For a simple read-only tool, this is adequate but not rich.

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

  Conciseness5/5

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

  The description is four short sentences, each serving a purpose: purpose, examples, return value, and usage. It is front-loaded with the core function and contains no fluff or redundancy.

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

  Completeness4/5

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

  For a simple two-parameter tool with no output schema, the description adequately covers purpose, usage, and return value. It lacks edge-case details (e.g., empty results) but is sufficiently complete for an agent to select and invoke the tool correctly. Sibling context makes the distinction from grep clear.

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

  Parameters4/5

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

  Schema coverage is 100%, providing baseline 3. The description adds value with pattern examples ('**/*.js', 'src/**/*.ts'), illustrating the accepted syntax beyond the schema's generic 'glob pattern' description. This pushes it to a 4.

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

  Purpose5/5

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

  The description clearly states the tool performs 'file pattern matching' and explicitly says it 'Returns matching file paths.' It distinguishes from siblings like grep (content search) and read (file reading) by focusing on finding files by name pattern, with concrete examples (**/*.js, src/**/*.ts).

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

  Usage Guidelines4/5

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

  It gives explicit usage guidance: 'Use it to find files by name pattern.' Avoids ambiguity about its purpose. However, it does not mention alternatives or exclusions (e.g., when to prefer grep for content search), which would make it a 5.

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

• skillA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It helpfully states that the output contains skill instructions and file references, which is useful since there is no output schema. However, it does not mention side effects, read-only nature, or error behavior for invalid names, leaving some gaps.

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

  Conciseness5/5

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

  The description consists of three sentences, each earning its place: purpose, output content, and name constraint. It is front-loaded with the primary action and contains no fluff or redundancy.

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

  Completeness4/5

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

  For a simple one-parameter tool with no output schema, the description covers the essential aspects: what it does, what the output contains, and the name constraint. It does not discuss error handling or prerequisite discovery steps, but these are minor for a loading tool.

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

  Parameters4/5

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

  The schema describes 'name' simply as 'Skill name', which is tautological. The description adds the crucial constraint that the name must match a discovered skill, providing meaningful semantics beyond the schema. This exceeds the baseline for high schema coverage.

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

  Purpose5/5

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

  The description starts with a specific verb 'Load' and a resource 'discovered specialized skill', clearly distinguishing it from sibling tools like file operations or web searches. The mention of 'discovered' further refines the tool's unique role.

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

  Usage Guidelines4/5

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

  The description clearly implies the context: use this when you need to load a discovered skill. It states the prerequisite that the name must match a discovered skill, but does not explicitly name alternatives or exclusions. Given the sibling tools, the use case is clear enough.

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

• webfetchA
  4.2/5.0
  Behavior4/5

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

  Even though no annotations are provided, the description states 'This tool is read-only,' which is a critical safety trait. It also discloses that format controls the output type and the default behavior (Markdown). This provides meaningful behavioral context beyond the schema.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the core purpose, followed by the key format detail and read-only safety note. Every word earns its place with no unnecessary filler.

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

  Completeness4/5

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

  For a simple fetch tool with 3 parameters and no output schema, the description adequately explains what the tool returns (formatted content) and its read-only nature. It doesn't cover error handling or redirects, but these are not essential for a basic fetch operation.

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

  Parameters3/5

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

  Schema coverage is 100%, so the baseline is 3. The description mentions 'format' and its default, but this is redundant with the schema description. It adds no additional meaning beyond what the schema already provides for url or timeout.

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

  Purpose5/5

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

  The description uses the specific verb 'Fetch content' and clearly identifies the resource as 'a fully formed HTTP or HTTPS URL'. This distinguishes it from sibling tools like 'read' (file reading) and 'websearch' (web search), making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description implies clear usage: use it when you have a complete HTTP/HTTPS URL. It also restricts to fully formed URLs, excluding relative or non-HTTP URLs. However, it does not explicitly mention alternatives or when not to use the tool, so it doesn't earn a 5.

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

• apply_patchA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries full responsibility for behavior. It discloses critical format constraints: the required '*** Begin Patch' and '*** End Patch' markers, allowed headers, the '+' prefix for new file lines, and the optional '*** Move to:' directive. This goes beyond surface description and helps avoid malformed patches, though it does not address error handling or atomicity.

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

  Conciseness5/5

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

  The description is only three sentences long but packs essential instructions. It starts with the primary purpose and then lists the required formatting elements without any fluff. Every sentence earns its place.

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

  Completeness4/5

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

  For a single-parameter tool with no output schema, the description covers the core usage well: it explains what to pass and how to structure it. It could be enhanced by mentioning what constitutes a valid patch (e.g., the need for at least one operation) or what happens on invalid input, but these are not critical for basic invocation. Overall, it is sufficiently complete.

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

  Parameters5/5

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

  The schema only describes patchText as 'full patch text', which is generic. The tool description provides essential semantics by specifying the exact patch syntax expected, including structure and examples of headers. This adds significant meaning beyond the schema and is crucial for correct invocation.

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

  Purpose5/5

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

  The description clearly states 'Apply an OpenCode patch document', which is a specific verb+resource. It also provides details on the patch format (Begin/End markers, headers), distinguishing it from sibling tools like write and edit that operate on single files directly.

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

  Usage Guidelines3/5

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

  The description explains the mechanics of creating a patch but does not explicitly state when to prefer apply_patch over write/edit. The phrase 'one or more file operations' implies batch use, but no direct comparison or exclusion criteria are given. Usage context is implied rather than explicitly defined.

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

• grepA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It reveals return format (paths, line numbers, matching lines), performance ('fast'), and the filtering behavior of the include parameter. It omits details like case-sensitivity and .gitignore handling, but offers meaningful transparency for a grep-like tool.

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

  Conciseness5/5

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

  The description is three sentences with no redundant phrasing. Purpose is front-loaded, and each sentence contributes distinct information: core function, include filter example, and return value characteristics.

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

  Completeness4/5

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

  For a simple tool with full schema parameter descriptions and no output schema, the description covers purpose, filtering, and output. It lacks edge-case behavior (e.g., binary files, symbolic links), but these are not typically critical for grep usage. Overall, the description is adequately complete for an agent to invoke correctly.

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

  Parameters4/5

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

  The schema already provides descriptions for all three parameters (100% coverage), so baseline is 3. The description adds value beyond the schema by giving concrete examples for the include parameter ('*.js', '*.{ts,tsx}'), which clarifies the expected format more precisely than the schema's 'File pattern to include'.

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

  Purpose5/5

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

  The description states it performs 'Fast regular-expression content search for codebases', specifying a clear verb, resource, and method. This distinguishes it from sibling tools like glob (which likely handles filename patterns) by focusing on content matching.

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

  Usage Guidelines4/5

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

  The description conveys clear usage context (regex content search) and gives an example of the include parameter, but does not explicitly name alternatives or say when NOT to use the tool. It implies when to use it based on the 'content search' phrasing, which is sufficient for typical cases.

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

• writeA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of disclosing behavior. It clearly states that an existing file is overwritten, which is the key destructive side effect. It does not mention auxiliary details like permission requirements or return values, but the core behavioral trait is well covered.

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

  Conciseness5/5

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

  The description is a compact two-sentence structure with no wasted words. The first sentence states the core function, the second adds important behavioral and usage guidance, making every word earn its place.

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

  Completeness4/5

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

  Given the tool's low complexity and complete schema, the description is nearly sufficient. It covers the primary operation, the overwrite behavior, and the alternative tool. It does not describe return values, but for a write operation this omission is minor and not required by the guidelines when no output schema exists.

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

  Parameters3/5

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

  The input schema already fully describes both parameters (filePath and content) with clear descriptions and 100% coverage. The tool description adds no new parameter-level detail, but it does not need to since the schema is self-sufficient. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool writes a text file to the local filesystem, using a specific verb and resource. It also distinguishes itself from the sibling 'edit' tool by noting when write is preferred, making the purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description explicitly tells the agent to prefer 'edit' for existing files when a targeted replacement is sufficient, providing a clear when-not-to-use condition and naming an alternative. This goes beyond simple context to give actionable guidance.

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

• readA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description fully carries the behavioral burden. It discloses default line limits, offset/limit behavior, line formatting, truncation, directory listing format, and attachment handling for images/PDFs—all beyond what the schema provides.

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

  Conciseness5/5

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

  The description is concise and every sentence adds value. It is well-structured, covering purpose, usage, output format, and edge cases in a compact set of sentences with no redundancy.

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

  Completeness5/5

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

  Since there is no output schema, the description adequately explains return values and formatting. It covers common edge cases like line limits, long lines, directories, and binary attachments, making it complete 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.

  Parameters4/5

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

  Schema coverage is 100%, so parameters are already documented. The description adds meaningful context: absolute path requirement, 1-indexed offset, default line count, line formatting, and directory trailing slash behavior, which enriches the agent's understanding beyond schema descriptions.

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

  Purpose5/5

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

  The description clearly states it reads a file or directory from the local filesystem, which is a specific verb+resource. It distinguishes itself from sibling tools like glob, grep, write, and edit by focusing on reading local content, and from webfetch by specifying local filesystem.

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

  Usage Guidelines4/5

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

  The description provides clear context: reading local files/directories, requiring absolute paths, and using offset/limit for large files. It does not explicitly name alternatives or exclusion criteria, but the context is sufficiently clear to avoid confusion with sibling tools.

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