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

With no annotations, the description carries the full burden and does so well: it discloses the destination path, that duplicates are avoided, that a save date is attached, and that superseded facts are not deleted but marked with date under ## Historial. Missing only auth/permission prerequisites and error behavior, which leaves a small gap.

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?

Front-loads the core action and path, then the example, then the supersede rule. Every sentence adds value, though the supersede clause is somewhat dense and could be split for readability.

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 mutation tool with an output schema (so return values need not be described) and no annotations, the description covers storage location, dedup, dating, and supersede behavior. It is nearly complete, lacking only permission or failure-mode 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?

Schema coverage is 0%, so the description must compensate; it explains `supersede` semantics thoroughly (pass the old fact text, marked not deleted, stored in Historial) and contextualizes `category` via the path and example. `fact` is self-evident by name, though the category default ('General') and valid range are not stated.

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?

States a specific verb (Guarda) and resource (un hecho duradero sobre el usuario) plus the storage target (memory/<category>.md), which distinguishes it from siblings like memory_history or write_file. The inline example makes the intent 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?

Gives a concrete usage example and, importantly, a conditional rule: use `supersede` when the new fact replaces an old one (changed address, job, etc.). It doesn't name sibling alternatives or state when NOT to use it, but the when-to-use guidance for the core parameter is explicit.

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

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

With no annotations provided, the description 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, the description carries the full behavioral burden, and it does disclose the single most important trait: it is non-mutating ('NO escribe el skill sola — devuelve el material'), preventing a false assumption that it creates the skill. It does not mention permissions/scope limits or rate behavior, but the return format is covered by the output schema.

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 tightly packed sentences: the first front-loads what it gathers and the downstream workflow, the second delivers the critical non-writing caveat. 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 single-parameter aggregation tool with an output schema, the description covers the source scope, the intended workflow, and the key caveat; return values are described by the output schema, so nothing essential 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?

Schema coverage is 0%, so the description must compensate. It gives `topic` concrete meaning by spelling out the three material classes it drives (fuentes, memoria, notas de conexiones), which goes beyond the bare string type 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?

States a specific verb (gather/aggregate) and resource (all material about `topic`: sources, memory, connection notes), plus the downstream purpose. It also explicitly distinguishes itself from the write siblings by declaring it does NOT write the skill, so an agent can tell it apart from write_file/save_url without opening any schema.

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 workflow is clear: call this to collect material, then the agent drafts the skill and persists it with write_file at skills/<topic-slug>.md. This routes the agent toward the correct downstream tool, though it stops short of explicit when-not-to-use or an alternative like search_knowledge/list_sources for narrower lookups.

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 present, the description carries the full burden and discharges it well: it discloses the multi-step process, that internet access requires user permission, that it uses user preferences, that it is slow, and crucially that it writes nothing to the vault ('No guarda nada en el vault'). That side-effect disclosure is exactly the kind of context annotations would otherwise supply.

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 paragraph is long but dense and front-loaded with the core process, then the no-write guarantee, the latency warning, usage condition, and parameter note. Nearly every sentence earns its place, though the verdict-category enumeration is somewhat verbose given an output schema exists.

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 structure need not be explained, yet the description still covers behavior, side effects, latency, permissions, and the parameter switch. For a complex multi-step tool with no annotations, this is nearly complete; only the 'text' parameter's exact role is left implicit.

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 compensate. It explains search_web clearly ('search_web=False: solo brain'), which is genuinely beyond the schema, but leaves 'text' undocumented (an agent must infer it is the claim to verify). Partial compensation for two parameters merits a 3.

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

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

The description states a specific verb and resource (verifies claims) and details the actual pipeline: separating claims, searching brain first, optionally searching the web, reading pages, grouping non-independent sources, and returning a rule-based verdict. This is clearly distinguishable from siblings like search_knowledge or read_url.

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 explicitly says when to use it ('cuando el usuario pida verificar algo o cuando haga falta comprobar un dato que no está en brain') and warns it is slow ('Tarda'). It does not name an alternative tool for the brain-only case, but the condition for use is unambiguous.

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?

No annotations are provided, so the description carries the full burden. It does disclose the key traits "Solo lee" (read-only, no mutation) and the hard limit of "hasta 10" notas, which is genuine behavioral context. However it says nothing about permissions/auth needs, rate limits, or behavior on unknown/missing node names.

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?

Effectively two sentences, both front-loaded with the most important fact ("Solo lee") and the usage context. Dense but every clause carries information; only the parenthetical reason list is slightly compressed.

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 format need not be explained, yet the description still outlines what comes back (neighbors, edge reasons, related, tags). Combined with the read-only statement, the parameter clarification, and the routing to propose_graph_change, an agent has enough to call it correctly without opening the schema.

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 compensate for the single undocumented parameter. It does so meaningfully by clarifying that each entry is a "nombre o ruta" (name or path) and that the array is capped at 10 items — information absent from the schema, which only says "array of string".

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

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

"Solo lee: para cada nota pedida (nombre o ruta, hasta 10), sus vecinos en el grafo y por qué están unidos..." states a specific read verb plus the resource (graph region/neighbors) and the payload (edges with reasons, related, tags). It is immediately distinguishable from mutating siblings like propose_graph_change and propose_connection, which it even names.

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 a clear when-to-use: "entender una zona del grafo antes de proponer un cambio con propose_graph_change" — naming the sibling alternative explicitly. It does not spell out a when-not-to-use case (e.g. use list_connections or vault_overview instead for global views), so it falls just short of a full 5.

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

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

No annotations are provided, so the description carries the burden, but a zero-parameter list operation has a low behavioral surface. It discloses the returned fields (name, active status, tools), which is helpful, though that partly duplicates the output schema; it does not state read-only safety or any side effects.

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?

A single compact sentence that front-loads the resource and then the returned fields, with no filler or repetition.

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

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

With zero parameters and an output schema present, the description need not explain return format, and it covers the essential identity of the resource. The only gap is the absence of when-to-use guidance relative to siblings.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-related the description needs to compensate for.

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?

Names the resource (connections) and immediately defines it as other MCP servers that brain re-exposes, plus the fields returned (name, active status, tools). This distinguishes it from list_sources, list_skills, and list_vault, though the differentiation is by resource name rather than an explicit contrast.

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?

There is no statement of when to use this tool versus alternatives such as list_sources, refresh_connectors, or propose_connection. The parenthetical definition implies a purpose, but no context or exclusion is given to route the agent.

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?

With no annotations, the description carries the burden. 'Lista' implies a read-only operation and it transparently discloses the returned fields, including failure errors and the generation of a short abstract for long sources. It does not, however, state permissions, pagination, or ordering behavior, so behavioral coverage is only partial.

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?

A single front-loaded sentence leads with the purpose before the parenthetical field list. The enumeration is somewhat long but every item is informative, so it earns its place with little waste.

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

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

An output schema exists, so return values need not be re-explained, and the description still usefully clarifies the 'abstract' field's purpose and its connection to read_file. For a parameterless read tool this is nearly complete, with only minor gaps around ordering or scope limits.

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 takes zero parameters, so the baseline is 4. The description's field enumeration describes outputs rather than parameters, adding no parameter meaning beyond the empty schema, but no compensation is needed for a parameterless tool.

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?

States a specific verb ('Lista') and resource ('todas las fuentes scrapeadas') with clear scope, and enumerates the returned fields (url, download/check timestamps, last error, .md path, title, abstract). This cleanly distinguishes it from siblings like list_vault, list_skills, and list_connections, which cover different resources.

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 a workflow by noting the 'abstract' field exists 'para decidir si leerla entera con read_file', effectively pointing to the read_file follow-up. However, it never states explicitly when to call this tool versus alternatives such as search_knowledge or list_vault, leaving usage to inference.

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 provided, so the description carries the full burden of behavioral disclosure. It describes the data provenance (facts replaced via supersede) and output contents, but does not state that the operation is read-only, whether it has side effects, or any permission or rate-limit considerations.

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 immediately identifies the resource, then adds the supersede context and return contents. It is appropriately sized with no redundant filler, though the parenthetical could be tightened.

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 parameter and an output schema, the description covers the essential data concept (superseded facts with date and replacement). However, it leaves gaps in usage guidance and parameter behavior, and does not compensate for the missing annotation safety profile.

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% for the single 'category' parameter. The description mentions 'de una categoría de memoria', which loosely maps to that parameter, but it adds no syntax, allowed values, default behavior, or filtering semantics beyond the parameter's name and schema 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 names the resource ('Hechos superados de una categoría de memoria') and scope, and references the sibling operation add_memory(..., supersede=...), which distinguishes it from add_memory. It lacks an explicit retrieval verb like 'list' or 'get', but the noun phrase makes the purpose clear enough for an agent.

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 what the tool returns and how superseded facts originate, but it gives no explicit when-to-use guidance, no when-not-to-use conditions, and no alternative tools to prefer. An agent must infer that this is for inspecting historical replacements.

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 substantial work: it discloses reversibility, protected-path exclusions, and a link-integrity side effect. It does not cover overwrite/collision behavior if dst already exists, so it is not fully complete.

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 primary action and example are front-loaded, followed by tightly packed clauses on recovery, exclusions, and link caveats. Every sentence 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 2-param mutation tool, the description covers reversibility, protected resources, and link side effects, and an output schema exists so return values need not be explained. Only collision/overwrite handling is unaddressed.

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 neither parameter has a description, so the schema alone does not explain src/dst. The example ("idea.md" -> "projects/idea.md") usefully conveys path formatting and the source/destination roles, but overwrite behavior and whether dst is a full path or directory are left unspecified.

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?

States a specific verb+resource ("Mueve o renombra una nota del vault") and backs it with a concrete example call, so the agent understands both move and rename semantics. It is clearly distinguishable from siblings like write_file, delete_file, and 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?

Explicitly names the recovery path (file_history + restore_file), lists protected paths that must NOT be moved (BRAIN.md, profile.md, memory/, knowledge/sources/), and adds a caveat about updating path-based links. It routes the agent to alternatives and states when-not conditions.

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 so well: it discloses the key non-mutating behavior (proposal pending user approval), the approval surface (chat/Conexiones), and auth handling (user logs in on approval for remote servers). Rate limits and return format are not covered, so not a 5.

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?

Front-loads the crucial 'does NOT add' fact, then uses tight bullets for remote vs local vs note. Dense but every line carries actionable information; minor redundancy between the note bullet and the closing instruction.

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 need not be described, and the description covers the behavioral and parameter essentials for a 7-param, zero-coverage proposal tool. Remaining gaps (exact approval mechanics, error cases) are minor against that coverage.

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 compensate, and it does — explaining url, command, args, env, headers, and note with concrete examples (npx/uvx invocations, {"GITHUB_TOKEN": "…"}). Only 'name' and some edge details are left unexplained, so strong but not exhaustive compensation for seven undocumented params.

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?

States a specific verb (propose/add) and resource (MCP server to brain's Connections), and crucially clarifies that it does NOT actually add the connection — the user approves it. An agent can distinguish this from list_connections or refresh_connectors without opening a schema.

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?

Gives clear operational context: remote servers use url, local servers use command+args, and it tells the agent to ask the user when a value (e.g. an API key) is missing before proceeding. No explicit when-not or named alternatives, but the usage model is well defined.

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 and does so: it discloses that nothing is changed, that the request is validated, that an image with marked changes is produced, and that the user approves or rejects with a click. This non-mutating preview/approval flow is exactly the behavioral context an agent cannot get from structured fields.

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?

Front-loads the core purpose and the non-mutating guarantee, then the payload format, then routing guidance. Every sentence earns its place, though the inline format specification for `changes` makes it denser than a purely prose 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?

For a two-parameter proposal tool with an output schema (the preview image) and no annotations, the description covers purpose, safety semantics, payload format, and sibling routing. Nothing an agent needs in order to call it correctly 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?

Schema description coverage is 0%, so the description must compensate and does: it enumerates the `changes` item shape (type with allowed values 'add_link'|'remove_link', source, target, optional label), the accepted note identifier forms (nombre, ruta o nombre de archivo), a limit of 10 changes, and that `reason` is a one-line rationale. This exceeds the bare schema, which types `changes` only as an unconstrained array of objects.

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?

States a specific verb and resource ('propone cambiar conexiones del grafo, el `related` de las notas') and immediately distinguishes itself from sibling write operations by declaring it is a proposal, not a mutation. An agent can tell this apart from set_frontmatter or write_file without opening a schema.

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 routes the agent: 'Usala en vez de set_frontmatter(related) cuando el usuario pida conectar o desconectar notas.' It names the alternative sibling and the triggering user intent, leaving nothing to inference.

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?

No annotations, so the description carries full burden. It does disclose the key non-destructive trait (returns text without saving to the vault), which is valuable. However it omits failure modes an agent would need: non-HTML/JS-rendered pages, paywalls, network errors, and the fact that output is truncated at max_chars.

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 tight sentences with the primary distinction (read-only, no vault persistence) front-loaded before the use case. 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?

An output schema exists, so return format needn't be explained, and the non-persistence behavior is covered. But with 2 parameters at 0% schema coverage and no mention of truncation or retrieval failure modes, the definition is not complete enough for an agent to call 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 0% and the description says nothing about either parameter. In particular max_chars (default 8000) controls truncation of the returned text, a behaviorally significant detail that is documented nowhere.

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?

States a specific verb and resource ('Lee una página web y devuelve su texto') plus the crucial scope boundary: it does NOT persist. It explicitly names the sibling save_url as the contrasting tool, so an agent can distinguish the two without opening either schema.

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?

Gives both a when-to-use ('leer la documentación de un server MCP antes de proponerlo') and an explicit alternative with its selecting condition ('para guardarla, save_url'), which is the exact routing decision this tool competes with.

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 behavioral burden. It implies a state-refreshing operation but never states whether it is safe/idempotent, whether it mutates stored state, what it costs, or what happens to tools from removed apps. For a refresh operation with zero annotation coverage this is a clear gap.

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?

A single sentence that front-loads the action and appends the trigger in parentheses. Zero waste, nothing to trim.

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

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

With an output schema present, return values need not be explained, and a zero-param tool has little surface to document. The trigger condition makes it usable. It nonetheless lacks any behavioral note (safety, side effects) that would fully close the loop in the absence of annotations.

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 takes zero parameters, so there is nothing to document and the schema coverage of 100% is trivially satisfied. The baseline for a 0-param tool applies, and the description correctly implies the operation applies to all active connections with no scoping input.

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?

States a specific verb+resource: re-discovering the tools of all active connections. An agent can grasp the operation immediately. However, it does not differentiate itself from the sibling refresh_sources, leaving the agent to infer the boundary.

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 an explicit trigger condition — 'después de conectar una app nueva' (after connecting a new app) — which tells the agent when this is warranted. It does not name alternatives (e.g. refresh_sources) or exclusions, so it stops short of full when/when-not 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, the description carries the full burden and mostly succeeds: it discloses that changed pages update the .md and indexes, that failures preserve the last good copy and log an error, and that runs can be slow. It omits auth/permission requirements, which is the remaining gap.

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?

Three short sentences, each front-loaded with new information: scope, success/failure behavior, then timing. 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?

An output schema exists so return values need no explanation, and the description covers behavior, error handling, and timing for an annotation-free tool. The missing piece is explicit routing against sibling tools such as save_url.

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 compensate, and it does: it names the path format (knowledge/sources/…) and explains the default ('todas si no pasás path') for the sole parameter, making the optionality meaningful.

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?

Starts with a specific verb+resource ('Vuelve a bajar una fuente guardada') and scopes it to saved sources under knowledge/sources/. This clearly distinguishes it from siblings like save_url (new URLs) and list_sources (enumeration).

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 states the two invocation modes (single path vs all when path is omitted), which implies when each applies. However, it never contrasts with alternatives like save_url or refresh_connectors, leaving the agent to infer routing.

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. It discloses two important negatives (no re-scrape, no embedding recalculation), but omits other behavioral traits such as required permissions, whether the index is overwritten, whether the operation is blocking, or what happens to existing index data.

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, no waste. The core action is front-loaded, followed by the use case and key exclusions. 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 zero-parameter interface and the presence of an output schema, the description covers what the tool does and its intended audience. It stops short of describing side effects or operational constraints (e.g., permissions, lock behavior), which would be helpful but are not strictly required here.

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 takes zero parameters, and schema description coverage is 100%. Per the rubric, zero parameters yields a baseline of 4; there is no parameter semantics for the description to add.

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?

States a specific verb and resource: rebuilds the keyword search index from .md files in knowledge/. It names the exact directories (sources, connections, composio) and distinguishes itself from embedding recalculation and re-scraping, making it easy to tell apart from siblings like refresh_sources.

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?

Clearly states when to use it (for sources saved before hybrid search existed) and when not to use it (does not re-scrape or recompute embeddings). No alternative tool is named explicitly, but the exclusion of re-scraping implicitly differentiates it from refresh_sources.

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?

No annotations are provided, so the description carries the full burden. It does disclose meaningful behavior: hybrid semantic/keyword retrieval and, valuably, the score semantics (None when only a keyword match occurred). However it omits operational constraints such as result limits, permissions, or how scoring/ranking is bounded.

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, front-loaded with the core purpose and with the retrieval modes and return shape following. Dense but efficient, with essentially no filler; it could be tightened slightly but every clause carries 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?

An output schema exists, so the return-value explanation is a bonus rather than a requirement. For a two-parameter search tool the description covers what it does and returns, but leaves out the when-to-use guidance and the top_k parameter, which is the main completeness gap.

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 neither parameter is named in the description. The aside about exact-word matching for 'proper names, IDs, dates, numbers' indirectly hints at what query content works well, but top_k is entirely undocumented and there is no explicit query-format guidance, so the gap is not compensated.

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?

States a specific action and resource: hybrid search over scraped sources plus captured connections, and names both retrieval modes (semantic + exact word). This is far more than a restatement of the name, though it does not explicitly differentiate itself from any sibling (none of the siblings are competing search tools, so the practical risk is low).

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 how the search works but never says when to reach for it versus alternatives like list_sources, read_file, or vault_overview. There are no exclusions, no prerequisites, and no guidance on choosing between this and other retrieval paths, so the agent must infer usage.

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

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

With no annotations, the description carries the full burden. It usefully discloses that content is preserved and that a null value deletes the field, but says nothing about permissions, whether it merges vs overwrites frontmatter, or behavior on files without existing frontmatter.

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?

Front-loads the core action, then adds example, null semantics, and a preference hint. Every clause earns its place; slightly dense but no padding.

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 need no explanation, and the two parameters are well covered. For a 2-param mutation tool the description is nearly complete, with only edge-case behaviors left unstated.

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 'fields' object is nested, yet the description compensates: it lists example keys (description, tags, related, name), shows a concrete call, and defines the null-deletes semantic that the schema does not. path is illustrated via the example.

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?

States a specific verb+resource ('Cambia campos del frontmatter') with an explicit scope note ('sin tocar el contenido') that separates it from whole-file rewrites. It is clear what it does, though it does not name a sibling like write_file directly.

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 recommends itself over rewriting the file 'cuando solo cambia un metadato', giving a clear condition that selects it against the write_file/append_file family. No when-not guidance beyond that, but the alternative is named.

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 at all, the description carries the full burden, and it discharges the most important part: 'No cambia nada' explicitly declares the operation is non-mutating and therefore safe to run at any time. It says nothing about cost, latency, or whether the scan can be large on a big vault, which is a minor remaining gap for a zero-parameter read 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 tight sentence plus a one-clause safety statement. The diagnostic targets are front-loaded as a scannable list and no sentence is 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?

An output schema exists, so return values need not be described, and the description still previews the categories of findings. For a zero-param read-only tool this is nearly complete; only the relationship to list_vault is left unstated.

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 takes zero parameters, so there is no parameter semantics to communicate; baseline 4 applies. The enumeration of what the overview reports (folders, orphan notes, tag variants) partially stands in for describing the output shape.

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?

States a clear verb+resource in substance: it produces a diagnostic overview of the vault for organizing it, and enumerates exactly what it surfaces (folders, loose notes, unlinked/undescribed notes, duplicate or variant tags, similar names). It does not, however, distinguish itself from the sibling list_vault, which an agent could easily confuse it with.

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?

'Para ordenarlo' implies the cleanup/organization scenario, which is a reasonable usage cue. But there is no explicit when-to-use vs. when-not, and no pointer to list_vault or search_knowledge as alternatives, so the agent must infer the choice.

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.