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

Annotations are absent, so description bears full burden. It only mentions output truncation, but not destructive potential, permission requirements, side effects, or command lifecycle. A bash command can modify files, yet this is unstated.

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?

Single, efficient sentence. Front-loaded with key information. No filler, but could add more without becoming verbose.

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?

No output schema, and description only notes output truncation. Does not explain error behavior, return codes, or how to interpret results. For an execution tool, this is incomplete.

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%, so baseline is 3. Description adds no extra meaning beyond the schema, which already describes command and project_path adequately.

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?

Clearly states it executes a bash command in the project directory. The verb 'execute' and resource 'bash command' are specific. Sibling tools like grep and read are distinct, so no 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?

No guidance on when to use this tool versus alternatives like grep or read. No mention of prerequisites, safe contexts, or 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?

The description discloses the key behavioral constraint that only one occurrence is replaced, which is valuable for an agent. However, with no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention what happens if old_string is not found, whether the operation is destructive/reversible, or any authorization requirements. Still, the 'one occurrence' note adds meaningful transparency beyond just stating 'edit'.

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 a single, succinct sentence that front-loads the action and includes the essential constraint. There is no fluff or repetition, making it appropriately concise for the tool's simplicity.

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

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

The tool has 4 required parameters and no output schema or annotations, yet the description is minimal. It lacks essential context about project_path, error behavior, return value, and prerequisites (e.g., file existence). This is under-specified for a tool with this many required inputs.

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

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

The description names old_string and new_string, giving them clear roles, but it does not explain file_path or project_path. Since the schema has 0% description coverage, the description must compensate, but it fails to clarify the relationship between file_path and project_path or their expected formats. Only partial parameter meaning is provided.

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: replacing one occurrence of old_string with new_string in a file. The verb 'replace' is specific, and the 'one occurrence' constraint distinguishes it from a bulk write or a replace-all operation. It is immediately clear from the description what this 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?

No guidance is provided on when to use this tool versus alternatives like 'write' or 'bash'. There is no mention of 'use this for targeted edits' or 'do not use this for full file rewrites'. Given the sibling tools, the description lacks explicit usage direction.

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 full burden. It does not disclose behavioral traits such as recursion behavior, hidden files handling, or pattern syntax support. The minimal description leaves 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.

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

The description is one sentence and front-loaded, but it is overly terse. While concise, it sacrifices necessary details about behavior and parameters.

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 output schema and no annotations, the description should provide more context. It lacks information on return format, error handling, and operational details like recursion depth or path resolution.

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 low (33%), with only 'search_path' described. The description does not add any parameter-level context beyond what the schema provides. It fails to explain pattern format or the role of required 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 finds files using a glob pattern under the project. It uses a specific verb ('find') and resource ('files'), which helps distinguish from sibling tools like grep and listdir, though not explicitly.

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 exclusions, prerequisites, or context that would help decide between glob and other file-searching 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?

With no annotations provided, the description carries full burden. It discloses the use of system grep recursive and line-number flags, but lacks details on safety (read-only), handling of binary files, or performance considerations. Adequate but could be more explicit.

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 a single sentence, very concise and front-loaded. However, it could include slightly more detail (e.g., return format) without becoming verbose. The current length is acceptable but just above minimal.

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 4 parameters, no output schema, and no annotations, the description is too terse. It does not explain output format, error handling, or how parameters interact (e.g., search_path vs project_path). More context is needed for an agent to use it confidently.

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 only 25% (only 'include' has a description). The description adds that 'pattern' is a regex, but does not explain 'project_path', 'search_path', or their defaults/relationships. The description should compensate for the low schema coverage but does not sufficiently detail parameter 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 clearly states the action ('Search for a regex pattern in files') and specifies the tool's behavior (uses system grep with -r -n). This distinguishes it from sibling tools like 'bash' or 'read'.

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 (for regex pattern searching in files) but does not explicitly contrast with alternatives like 'bash' (which could also run grep) or 'search_compliance_docs'. No guidance on when not to use this tool.

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

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

With no annotations, the description carries the full burden and does well: it discloses the full pipeline (cloud parsing, DLP scrubbing, chunking/embedding, audit) and the post-condition that contents become searchable on the returned collection. Missing details like permissions or failure modes, but this is substantially transparent for an ingestion tool.

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

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

The description is three sentences, front-loaded with the action and outcome. Every clause adds value: formats, security, processing, and subsequent searchability. No filler or redundancy.

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

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

For a two-parameter tool with no output schema, the description explains end-to-end behavior and tells the agent what the caller gets (a collection usable with search_compliance_docs). It is complete enough to select and invoke correctly 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?

Schema coverage is 100% and already provides detailed descriptions for both path and collection, including the namespace rule. The description adds a local-file emphasis and the concept of a returned collection, but doesn't materially improve on the schema's parameter guidance, so the baseline 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 states exactly what it does: uploads a local file into the Proofpane governance RAG corpus. It clearly distinguishes from siblings like search_compliance_docs by framing this as the ingestion side and explaining that retrieval happens separately.

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

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

Explicitly instructs when to use: 'Use when the user wants a local document made available for governed retrieval / Q&A.' It also points to search_compliance_docs as the retrieval alternative. It doesn't explicitly list when-not-to-use scenarios or exclusions, but the usage context is clear.

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

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

With no annotations provided, the description carries full burden. It does not disclose behavioral traits like recursion, filtering, or whether it reads the directory or simulates. Only a single verb 'list' implies reading, but no further details.

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?

Single sentence, no wasted words. However, the conciseness comes at the cost of completeness; it is appropriately sized for its simplicity, but lacks necessary detail.

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

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

Given no output schema and no annotations, the description fails to cover return format, error conditions, or whether the listing is recursive. For a simple directory listing tool, it is insufficient for an AI agent to confidently select and invoke 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 has two parameters (project_path required, dir_path optional) with 0% schema description coverage. The description adds no meaning beyond the parameter names—no explanation of what each parameter does, how they interact (e.g., dir_path relative to project_path), or default behavior.

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

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

Description states 'List contents of a directory' which is a specific verb-resource pair, but it is vague about what 'contents' includes (files, subdirectories, both?) and does not distinguish from sibling tools like bash (which can ls) or glob (which pattern-matches 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?

No guidance on when to use this tool versus alternatives (e.g., bash ls, glob). No context on prerequisites or limitations.

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 given, the description carries the full burden for disclosure. It adds a meaningful behavioral constraint: 'Path traversal is blocked.' However, it does not explain return values, error behavior, or permissions. The security note is useful, but the description remains minimal.

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 consists of two short, purposeful sentences. The primary action is front-loaded, and the security warning is appended without redundancy. No filler words—optimal 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 simple read operation with fully specified parameters, the description adequately conveys purpose and a key constraint. The return value (file contents) is implied by 'read,' and error handling is not critical for a basic tool. While it doesn't explicitly mention return format, it is sufficiently complete for an agent to use 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?

The input schema fully describes both parameters (file_path as relative path, project_path as absolute root). The description only repeats the phrase 'project directory' and adds no parameter-specific semantics beyond the schema. With 100% schema coverage, 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 clearly states the tool's action: 'Read a file from the project directory.' The verb 'read' and resource 'file' are specific, and the tool is distinct from siblings like write/edit (which mutate) and grep/glob (which search). However, it does not explicitly name alternative tools, so it stops short of a 5.

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

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

No guidance is provided on when to use this tool versus other directory/search tools like listdir, grep, or glob. The description does not mention any prerequisites, exclusions, or scenario-based recommendations. This is a clear gap.

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, the description must disclose behavior. It does state the return format ('top N matching chunks with source + relevance score') and the default/override behavior for collection. However, it does not explicitly state that the operation is read-only or disclose any potential side effects, rate limits, or auth requirements.

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

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

Two sentences with no filler. The first sentence front-loads the core purpose; the second adds configuration nuance. Every sentence earns its place.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description provides sufficient context: purpose, return shape, default behavior, override capability. It could mention edge cases or limits on top_k, but for a RAG search tool this is largely 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 baseline is 3. The description adds context by explaining the default collection/retrieval method and that top N corresponds to top_k, which is marginally helpful but doesn't add significant new 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 action ('Search') targeting a distinct resource ('Proofpane governance / compliance document corpus') and specifies the mechanism ('cloud RAG service'). This clearly differentiates it from sibling search tools like grep or session_search despite not naming them explicitly.

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 explains default configuration behavior and collection overrides, but it does not provide guidance on when to use this tool versus siblings like grep or session_search. Usage context is implied ('compliance document corpus') but no explicit alternatives or exclusions are given.

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, the description carries the behavioral burden. It discloses that searches are 'governed' (implying access control) and mentions FTS5, but 'governed' is ambiguous. It does not state whether the tool is read-only, what happens with no args (browse recent is stated), or any rate limits or side effects. Since the description adds some context but lacks precision, a 3 is appropriate.

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, front-loaded with the core purpose, and uses a clear colon-separated structure for modes. Every sentence adds value with no redundant content.

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 7-parameter tool with four modes and no output schema, the description covers the main usage patterns well. It doesn't explain return format or edge cases, but it provides enough for an agent to select and invoke the tool correctly for the primary tasks. The schema fills in some remaining parameter details.

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?

Despite only 57% schema coverage, the description adds significant meaning by mapping parameter combinations to use cases (query for discovery, session_id for whole session, session_id+around_message_id for scrolling, no args for browse). This goes beyond schema bare descriptions, though it leaves sort and role_filter unaddressed, which the schema partially documents.

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

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

The description clearly states it searches and recalls past Hermes conversations, and distinguishes from siblings like grep and search_compliance_docs by explicitly scoping to conversations. The multiple usage modes (discovery, read session, scroll, browse) further clarify the tool's purpose.

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

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

Provides concrete usage scenarios with argument combinations (query for discovery, session_id for reading, etc.), which implies when to use each. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full exclusion 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?

No annotations exist, so description carries full burden. It mentions 'governed — every write is policy-gated + audited', which discloses policy enforcement and auditing. However, it does not cover idempotency, error handling, or return values. Adequate but not comprehensive.

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?

Single sentence, no redundant words. All information is front-loaded. Every phrase adds value: actions, resource, governance. This is an efficient use of space.

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?

Tool complexity is high (9 params, multiple actions, no output schema). Description covers core purpose and a key behavioral trait (governance) but omits details like return format, error cases, and parameter constraints. Sufficient for a basic understanding but leaves gaps for 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 67%, so schema provides some meaning. The description adds no parameter-level detail beyond naming actions; it does not explain how parameters relate to actions or indicate dependencies. For 9 parameters, more guidance is needed.

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

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

Description clearly lists all actions (create, edit, patch, delete, write_file, remove_file) on the resource 'skill'. It distinguishes from sibling tools like skills_list and skill_view, which are read-only. Verb+resource is specific and unambiguous.

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

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

Description implies write operations but does not explicitly state when to use this tool versus alternatives. Given siblings include skills_list and skill_view, explicit guidance on when to use each would improve clarity. Currently, usage context is only implied by the tool's name and actions.

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 provided, so description carries full burden. Mentions 'governed' but lacks details on authentication, rate limits, or side effects. Sufficient for a read-only list tool.

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

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

One concise sentence front-loading key information with no unnecessary 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?

For a simple 1-param, no output schema tool, description covers purpose, output fields, and filter. Lacks details like pagination but overall 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?

Adds basic meaning with 'Optional category filter' but does not elaborate on valid values or behavior. Schema coverage is 0% so description partially compensates.

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?

Clearly states verb 'List', resource 'Hermes skills', and includes output fields (name, description, category). Distinguishes from siblings like skill_manage and skill_view.

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?

Indicates use case for listing skills with optional category filter, but does not explicitly state when not to use or provide alternatives among siblings.

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

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

No annotations are provided, so the description carries the full burden. It states 'Read' implying a read-only operation but does not disclose any other behavioral traits (e.g., authentication requirements, rate limits). The vague term 'governed' adds minimal value.

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 a single sentence that is front-loaded with the primary action. It is efficient but lacks structure; however, no word is wasted.

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 simplicity of the tool (two params, no output schema), the description adequately states the core functionality. However, it does not explain the return format (e.g., full file contents as a string) or elaborate on 'governed' behavior. It is sufficient but not thorough.

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 baseline is 3. The description adds context that file_path can link to 'reference/template/script files', slightly surpassing what the schema provides ('Optional linked file, e.g. references/api.md'). However, it does not add significant new 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 explicitly states it reads a skill's SKILL.md and optionally linked files via file_path. The verb 'Read' and resource 'skill's full SKILL.md' are specific, and it distinguishes from siblings like 'read' (generic file read) and 'skill_manage' (management 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 does not provide explicit when-to-use or when-not-to-use guidance relative to siblings such as 'read' or 'grep'. The term 'governed' hints at access control but is not elaborated. No alternatives are mentioned.

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 two important behavioral traits: overwrites existing content and automatically creates parent directories. With no annotations, this is useful but incomplete. It does not mention prerequisites, permissions, reversibility, or what happens if the file does not exist, which are expected for a mutation tool.

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

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

Two short sentences deliver the core functionality and key side effects without filler. The description is front-loaded with the primary action and immediately notes the overwrite behavior, making it highly 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 three required parameters, no output schema, and no annotations, the description is too sparse. It does not explain the role of 'project_path', any return value, or error conditions. The presence of sibling tools like 'edit' and 'read' also calls for clearer contextual differentiation.

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, so the description must compensate. It mentions 'content' and 'file' which loosely map to 'content' and 'file_path', but does not address 'project_path' at all. The meaning of the file location relative to project root is unspecified, leaving a key parameter unclear.

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 'Write content to a file' with the specific verb 'write' and resource 'file'. The parenthetical '(overwrites)' hints at behavior that distinguishes it from siblings like 'edit', giving enough clarity for purpose.

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

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

It gives minimal context on when to use (writing/overwriting a file) but provides no explicit guidance on when not to use it or alternatives. It also does not clarify how it differs from sibling tools like 'edit' beyond the overwrite hint, leaving the agent to infer usage boundaries.

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