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

With no annotations, the description carries the behavioral burden. It discloses the durable write behavior, the category-based file path, and deduplication. It does not describe failure modes or response details, but the output schema covers the latter and the main side-effect behavior is well communicated.

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 zero filler. The core purpose, storage location, dedup behavior, and a useful invocation example are all packed into a very compact description.

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

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

The tool is simple, has an output schema, and the description covers purpose, file location, deduplication, and parameters via example. The only notable gaps are the missing explicit mention of the default category and lack of guidance about when not to use it, but these are minor for successful 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 descriptions are absent, so the description must compensate. It partially does by providing a concrete example mapping 'fact' to a preference string and 'category' to 'Preferencias', and by showing how category influences the file path. However, it does not explain that category defaults to 'General', which is only visible in the schema.

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

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

The description clearly states the action ('Guarda un hecho duradero sobre el usuario'), the storage target ('memory/<category>.md'), and a key behavior ('sin duplicar'). The example further clarifies exactly what kind of content belongs here, distinguishing it from generic file-writing tools.

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 the tool: when persisting durable user facts/preferences rather than writing arbitrary files. However, it does not explicitly name alternatives or exclusions, such as when to prefer write_file, append_file, or search_knowledge instead.

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 must carry the full burden. It discloses that the file is created if missing and that the action is recorded in history ('Queda en el historial'). However, it doesn't disclose potential side effects like overwriting, permission requirements, or error behavior, and it doesn't explicitly state whether the operation is atomic or reversible.

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, front-loaded with the core action and key exception (creating if missing). No wasted words; the history note is a useful extra. The structure is ideal for quick parsing.

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 is simple, and the description covers the essential behavior. However, it lacks details on return values (despite having an output schema), path syntax, and how it differs from write_file. Given the low complexity, this is adequate 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 coverage is 0%, so the description must explain both parameters. It refers to 'content' but doesn't clarify what format is expected or how 'path' should be specified (relative/absolute). The description adds minimal value beyond the raw parameter names.

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

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

The description clearly states the verb 'Agrega' (adds) and the resource 'archivo del vault' (vault file), and includes the key behavior of creating the file if it doesn't exist. It's specific enough to distinguish from read_file or delete_file, though it doesn't explicitly contrast with write_file or str_replace_file.

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 choose this tool over siblings like write_file (overwrites) or str_replace_file (replaces). The description implies appending as a distinct operation but never states when it's appropriate or preferable, leaving the agent to infer from context.

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 usefully discloses that deletion is recoverable via file_history + restore_file, a key behavioral trait. However, it does not mention permissions, behavior for missing paths, or whether deletion is permanent under some 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 a single, compact sentence with the primary action front-loaded and the recovery note appended. Every phrase earns its place with no 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 low-complexity tool with one required parameter and an output schema, the description is nearly complete: it states the action and the recovery path. The main gap is missing parameter semantics for path, which prevents a perfect score.

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 only parameter, path, has 0% schema description coverage, and the description does not clarify what format path should take (vault-relative, absolute, file extension rules, etc.). The agent is left with only the schema's generic 'Path' title.

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: 'Borra un archivo del vault' (deletes a file from the vault). It clearly identifies the tool's core operation, though it does not explicitly contrast itself with sibling tools.

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?

Usage is implied: use this to delete a vault file. It also names file_history and restore_file as recovery alternatives, which hints at when recovery might matter, but it gives no explicit when-to-use or when-not-to-use 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?

With no annotations provided, the description bears the full burden. It discloses the ordering (newest first) and the fields, which is useful. However, it doesn't mention whether this tool mutates anything (it's likely read-only), what happens if the path doesn't exist, or details about pagination/limits. These gaps are not severe for a list operation.

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 concise sentence with no filler. It front-loads the purpose and includes the key detail about the id being for restore_file, which is crucial for routing.

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?

There is an output schema, so return details are covered. The tool is simple with one param, and the description covers the basics. However, given the siblings include restore_file, it would help to mention that this is a read-only overview before restore. Also, path syntax is not specified, which could cause incorrect calls.

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 only parameter, path, is self-explanatory, but schema coverage is 0%, meaning the description must add meaning. The description implies the path points to a vault file, but doesn't clarify path format (e.g., relative to vault root). Since coverage is 0%, a baseline 1 might be argued, but the description's mention of 'archivo del vault' gives some context, so a 3 is fair.

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 lists versions of a vault file, newest first, with fields id, date, and operation. It distinguishes from siblings like read_file and restore_file by focusing on history. However, it doesn't explicitly name a sibling for comparison, making differentiation slightly implicit.

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 for viewing file versions, and mentions that the id is used for restore_file, which hints at when to use it (before restoring). But it doesn't provide explicit exclusions or alternatives; an agent might need to infer when to use this vs. read_file.

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 present, so the description carries the burden. It accurately states the operation (returns content) and demonstrates accepted name formats, but it does not disclose behavior on missing skills, extension normalization, or whether the operation is read-only beyond the verb 'Devuelve'.

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, front-loaded with the action and resource, with useful examples. No 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 one-parameter getter with an output schema, the description is largely sufficient: it specifies the resource, the input format, and the returned content. It could add a pointer to list_skills for discovery or error behavior, but these are not critical 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 coverage is 0%, and the description compensates by explaining that 'name' accepts either 'mi-skill' or 'mi-skill.md'. This adds format flexibility beyond the bare schema, though it does not specify case sensitivity or resolution rules.

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

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

The description uses a specific verb ('Devuelve') and resource ('contenido de un skill') and gives two accepted name formats. It clearly identifies the tool as a skill-content getter, though it does not explicitly contrast it with list_skills or read_file.

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 when-to-use or alternative guidance is provided. It implies use when you need a skill's content by name, but does not mention list_skills for discovery or read_file for arbitrary files, nor any exclusions.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the exact source files it lists, that it includes descriptions, and that it is a listing operation rather than a mutation. It does not state read-only behavior explicitly, but 'Lista' and the file pattern make the non-destructive nature clear.

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 efficient sentence that front-loads the action, specifies the source location, states what fields are included, and explains the purpose. Every phrase earns its place with no 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 parameterless listing tool with an output schema, the description is complete: it tells an agent what will be listed, where it comes from, what metadata is included, and why the tool should be used. Nothing critical is missing 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?

The tool has zero parameters, so there is no parameter documentation burden. The description correctly avoids inventing parameter details, and the empty input schema already communicates that no arguments are 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?

The description states a specific verb ('Lista'), a clear resource ('skills'), and a precise source pattern ('skills/*.md'). It also says the listing includes each skill's description and names the purpose ('para decidir cuál aplica'), which distinguishes it from sibling tools like get_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 description provides clear usage context: use this tool to review available skills and their descriptions when deciding which skill to apply. It does not explicitly mention exclusions or contrast it with get_skill, but the intended decision-making scenario 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?

No annotations are provided, so the description carries the behavioral disclosure burden. The verb 'Lista' clearly indicates a read-only operation and explicitly states the output fields, which is adequate for a parameterless listing tool. It does not mention potential pagination or data freshness, but these are minor for this simple use case.

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 with a parenthetical list of fields, front-loading the core action and resource. Every word earns its place with no redundant 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?

An output schema exists, so return-value details are already structured. Combined with zero parameters, the description is sufficient for correct invocation. The only minor gap is not clarifying how 'sources' relate to sibling list_vault, but that does not block usage.

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 tool has zero parameters and schema description coverage is 100%, so there are no input semantics to clarify. The baseline of 4 applies because the description cannot add value for parameters that do not exist.

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 uses a specific verb ('Lista') with a clear object ('todas las fuentes scrapeadas') and enumerates the returned fields (url, fecha, path del .md, título). This makes the tool's scope unmistakable and differentiates it from siblings like list_vault and list_skills by resource type.

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 given on when to use this tool versus alternatives such as list_vault, search_knowledge, or save_url. There are no explicit conditions, exclusions, or references to sibling tools, so an agent must infer the appropriate context.

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 available, the description carries the full burden of behavioral disclosure. It correctly implies a read-only operation ('list') and specifies the output content (path + description). However, it omits behavioral details such as recursion, ordering, or handling of hidden files, which could matter in edge cases.

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, concise sentence that front-loads the primary purpose and includes an illustrative example. Every component earns its place without redundancy or excessive 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?

For a simple tool with one optional parameter, the description provides the core information needed: what it returns (paths and descriptions) and how prefix works. The presence of an output schema (not shown) reduces the need to explain return values. Missing details like whether files are listed recursively are likely minor for typical usage.

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 provides no description for the 'prefix' parameter, leaving 0% schema coverage. The description adds meaning by stating it is optional and giving an example ('projects'), which implies it filters by path prefix. This is sufficient for the agent to understand the parameter's role.

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

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

The description clearly states the verb 'list' and the resource 'vault', specifying that it lists .md files with their path and frontmatter description. It does not explicitly name sibling tools to differentiate itself, but the purpose is unambiguous. The optional prefix is mentioned, adding specificity.

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

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

No guidance is provided on when to use this tool versus alternatives like search_knowledge or list_sources. The description only explains what the tool does, not the contexts where it is preferred. There are no directives on prerequisites or exclusions.

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

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

No annotations are present, so the description carries the burden. It states the tool returns the complete file content and that the path is vault-relative, which is useful. It does not disclose error behavior, encoding, or explicitly confirm no side effects, though 'Devuelve' implies a read-only operation.

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, front-loaded sentence with no filler. Every piece of information — return value, scope, and path format — is useful and immediately accessible.

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 one-parameter read operation with an output schema present, the description covers everything needed to invoke it correctly: the action, the result, and the path convention. No additional context is required.

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 only lists 'path' with no description, so the description adds critical meaning: the path is relative and should be within the vault, with 'BRAIN.md' as an example. This fully compensates for the 0% 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 uses a specific verb ('Devuelve') and a specific resource ('contenido completo de un archivo del vault'), and gives a concrete path example. This clearly distinguishes read_file from write/delete siblings.

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?

Usage is implied: the tool returns file content, so an agent can infer when to use it. However, there is no explicit guidance about when to choose this over alternatives like list_vault or file_history, and no exclusions 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?

With no annotations provided, the description carries the full burden of disclosing side effects. It states that restoration adds to the history and is therefore undoable, which is a key behavioral trait. It does not mention permissions or error behavior, but for a simple mutation tool, this is adequate and goes beyond a bare 'restore' statement.

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 two sentences, with the core action front-loaded and the side effect (history entry/undoability) in the second sentence. Every word earns its place; there is no fluff 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 tool with only two required parameters and an output schema (not detailed), the description covers the action, the source of version_id, and the reversibility. It does not detail when to use vs. alternatives, but that is addressed under usage guidelines. Overall, it is sufficient for an agent to call it correctly without 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 schema has zero description coverage for both parameters, so the description must compensate. It explains that version_id refers to a version from file_history, giving context that the schema lacks. Path is implicitly understood as the file to restore. This adds meaningful semantics, though it could be more explicit about the path parameter.

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 a specific verb and resource: 'restore a file to how it was in version version_id'. It distinguishes itself from siblings like read_file, write_file, and file_history by focusing on the action of restoring a prior version, which is 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?

It references 'file_history' as a source for version_id, implying the agent should consult history first to obtain a valid version. However, it does not explicitly state when to use this tool over alternatives like write_file or when not to use it. The guidance is implied rather than explicit, so it falls short of a higher score.

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 disclosure burden. It states the side effects (scrapes, chunks, indexes in Chroma, writes/updates a markdown file), explains the no-duplicate update behavior, and discloses the Playwright fallback path plus the flag that forces it.

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 core pipeline is front-loaded first, followed by the update behavior and the conditional render_js logic, so an agent can quickly parse the essential information.

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

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

For a two-parameter side-effecting tool with an output schema, this is complete: it names target storage, the on-disk output location, update semantics, and the JS-rendering fallback. No critical invocation detail is missing.

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?

Even though schema description coverage is 0%, the description adds real meaning to render_js by explaining the normal fetch path, the fallback condition, and the forced direct path. The url parameter is self-explanatory from its type and the tool's stated purpose.

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

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

The description opens with a specific verb (Scrapea) and resource (una URL), then lists the concrete pipeline: chunking, indexing in Chroma, and creating/updating the .md file in knowledge/sources/. This clearly separates it from the file and knowledge sibling tools.

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

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

It provides clear context: use this to save a URL into the knowledge base, and it can update an existing entry without duplicating. It does not explicitly name alternative sibling tools or give when-not-to-use guidance, but no direct sibling competes with this ingestion behavior.

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 burden of behavioral disclosure. It reveals that the tool performs semantic search and returns chunks with url and source_md_path, but it does not explicitly state read-only behavior, authentication needs, rate limits, or error behavior. It 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.

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

The description is a single, front-loaded sentence that leads with the operation and then the return shape. There is no filler, redundancy, or unnecessary 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?

The tool is simple, has an output schema, and the description conveys the core search behavior. However, the 0% parameter coverage and lack of usage guidance leave an agent to infer details about top_k and when this tool should be chosen over siblings. It is adequate but not fully 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 0%, so the description needed to compensate. It adds meaning to the query parameter through 'Búsqueda semántica' but says nothing about top_k, result limits, or how the query is interpreted. The schema's default value is the only clue for top_k.

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 names a specific operation ('Búsqueda semántica') and a specific resource ('fuentes scrapeadas'), and it states the return shape ('chunks con url y source_md_path'). This makes the tool's purpose clear and distinguishes it from file-management and source-listing siblings.

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 that this tool is for querying scraped knowledge rather than for file operations or listing sources, but it does not explicitly state when to prefer it over alternatives or when not to use it. No exclusions or sibling comparisons are provided.

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 of disclosing behavior. It does state a critical constraint: 'old' must appear exactly once, and that the change is recorded in history (implying reversibility). However, it does not disclose what happens if the constraint is violated (e.g., failure or error), whether the operation is destructive, or what the response contains. It provides partial transparency but lacks important 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?

The description is a single concise sentence, front-loading the key constraint and history note. It avoids unnecessary words and conveys the essential behavior in minimal space. It could be slightly more structured (e.g., separating constraint and history), but it is efficient and 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?

For a tool with no annotations, an output schema, and three required parameters, this description is insufficiently complete. It omits error behavior (what if 'old' is missing or appears multiple times), return values, and prerequisites. It also lacks any comparison to sibling tools, which are numerous. An agent would need to open the schema or experiment to understand full usage, making this a minimally viable but incomplete definition.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meanings. It mentions 'old' and its uniqueness constraint, but does not explicitly define 'path' (file location) or 'new' (replacement string). An agent could infer these from the tool name, but the description adds minimal value beyond the schema's bare property names. The constraint on 'old' is useful, but the other two parameters are undocumented.

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 ('reemplazo' = replace), the resource (file), and the key constraint that 'old' must appear exactly once. It distinguishes itself from siblings like write_file or append_file by implying a targeted replacement rather than a full overwrite or addition. However, it does not explicitly mention the 'path' or 'new' parameters, relying on inference from the tool name.

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 siblings. It doesn't say 'use this for single-occurrence replacements, use write_file for full rewrites'. The uniqueness constraint hints at a scenario, but it does not contrast with alternatives or state exclusions. The agent must infer usage from the name and context.

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

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

With no annotations provided, the description carries the behavioral burden. It clearly indicates a mutating action (create/replace entirely) and adds a notable side effect: the operation is recorded in file_history. This goes beyond a bare 'writes' and covers a meaningful behavior, though other traits (e.g., overwrite confirmation) are absent.

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 extremely concise, comprising two short phrases with no wasted words. The primary action is front-loaded, and the history note is appended efficiently. Perfectly sized for its simple purpose.

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?

An output schema exists, so return values are covered. The description covers the core action and history side effect. However, with no annotations and sibling partial-edit tools, it could be more explicit about when to choose this over append_file or str_replace_file. The ambiguity is mitigated by 'entero' but not fully resolved, leaving minor gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain the 'path' or 'content' parameters at all. Although the parameter names are self-explanatory, the description adds no meaning or format expectations beyond the bare schema, failing to compensate for the coverage gap.

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 creates or completely replaces a file in the vault, using the verb 'Crea o REEMPLAZA ENTERO' which distinguishes it from partial-edit siblings. It identifies the resource (vault file) and implies full-file operations, though it doesn't explicitly name alternatives.

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 (create or fully overwrite a file) but does not state when not to use it or explicitly mention alternatives like append_file or str_replace_file for partial edits. The 'entero' hints at full replacement but lacks explicit routing.

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