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

With no annotations, the description carries full burden. It discloses the key failure condition (file exists) and implies the group must already exist, but doesn't mention success return or permission requirements. This is adequate for a simple add 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?

Two sentences, first states purpose, second provides important failure behavior and alternatives. No wasted words.

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

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

Given the output schema exists and the tool is simple, the description covers purpose, failure condition, usage guidance, and implies prerequisites. It is complete within 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 descriptions cover all three parameters (ref, path, content) with clear details like path rules and content meaning, so the description adds no extra parameter info beyond the schema's baseline.

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 adds a new file to an existing artifact group, distinguishing it from edit/remove operations. The failure clause clarifies it's for creating new items, not modifying existing ones.

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

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

Explicitly instructs to use edit_artifact_group_item when changing an existing file and to read_artifact_group first when uncertain, providing clear alternatives.

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 transparency burden. It discloses that the author appears as the API key prefix, that entries include commit message, content fingerprint, and current head status, and that results are newest first. This covers user-facing behaviors and consequences without being verbose. It does not explicitly state it's read-only, but the verb 'List' strongly implies no mutation.

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

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

The description is compact and well-structured: a one-sentence purpose, a summary of entry fields, and a follow-up usage note. No filler or repetition of schema details. Every sentence adds value, and the structure is easy to scan.

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

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

The tool has a moderate complexity with an output schema (though not inspected), and the description provides enough context for an agent to use it correctly: what to expect in entries, how to handle pagination via limit, and how to connect results to read_artifact/write_artifact. The description covers the complete workflow without requiring extra inference. Given the presence of an output schema, return values need not be fully restated.

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 full descriptions for all three parameters (ref, full, limit), including defaults and max value. The description's only pointer is 'Use the returned version ids', which hints at the output structure rather than the parameters. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool 'List the version history (git commits) of a mutable artifact, newest first.' This specific verb+resource distinguishes it from sibling tools like read_artifact and write_artifact, which handle individual versions. The mention of git commits and mutable artifacts clarifies the exact scope.

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 explicitly tells the agent to use the returned version ids with read_artifact to inspect old iterations or write content back to revert. This is useful guidance on follow-up actions, but it does not explicitly contrast when to use this tool versus alternatives like memory_history, which is similar in purpose. Still, the context is clear enough for a focused history tool.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states the claim takes effect immediately and that the address serves the user's public vault as soon as the call returns. It also discloses naming constraints and the Pro account limit, which are behavioral factors. It does not cover error cases (e.g., duplicate claim) or reversibility, but the given information is substantial.

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

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

The description is compact and well-structured: first sentence states the purpose, second explains the immediate effect, third gives naming constraints, and fourth covers the account limit. Every sentence adds relevant information without redundancy or fluff.

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

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

Given the tool's moderate complexity and the presence of an output schema (which covers return values), the description is reasonably complete. It explains the action, the effect, validation rules, and account limitations. It does not detail error handling or prerequisites like authentication, but these are likely conveyed in API errors or are implicit. Overall, it provides sufficient context for effective use.

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

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

The input schema already provides descriptions for both parameters (desired_name and base_domain) with 100% coverage, so the baseline is 3. The description adds meaningful details beyond the schema: the accepted character set and length range for desired_name, and the example 'nova' reinforces the expected format. It also explains that every subdomain serves the full vault, which clarifies the impact of the desired_name 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 action (claim a vanity subdomain) with a concrete example (nova.vault.cool) and the resource affected (the user's vault). It is distinct from sibling tools, none of which deal with subdomains, so it 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?

The description implies when to use this tool (to obtain a vanity subdomain for the vault) and provides constraints that guide usage: naming rules (lowercase letters, digits, hyphens, 2–63 characters) and the Pro account limit of 10 subdomains. It does not explicitly mention alternatives or exclusions, but no obvious alternative exists among siblings. The context is clear enough for an agent to decide appropriately.

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 that connections are bidirectional, appear as edges in the vault's graph view, and support any artifact/memory combination. It does not mention idempotency or duplicate handling, but the provided behavioral details meaningfully exceed a bare mutation 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 three-sentence structure is front-loaded with the primary purpose, followed by behavioral scope and a usage prerequisite. No information is redundant, and each sentence earns its place without 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?

Given the tool's simplicity (2 required parameters, output schema present), the description fully covers what it does, accepted item types, relationship semantics, and the discovery prerequisite. There are no significant gaps for an agent to invoke the tool correctly.

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

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

The input schema already provides 100% coverage of both parameters, including accepted formats (id, slug, exact title) for artifacts and memories. The description adds context about allowable combinations but no new parameter syntax or semantics, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Connect'), a clear resource ('two items already in the user's HyperVault'), and explicitly enumerates the allowed combinations (artifact↔artifact, memory↔memory, memory↔artifact). This distinguishes it from sibling tools that create or modify items or groups, making the tool's purpose 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?

The description gives an explicit prerequisite: 'Use list_my_vault_items or recall_from_memory first to find the right items.' It also implicitly excludes new items by emphasizing 'already in the user's HyperVault.' However, it does not explicitly contrast with alternatives or list when not to use the tool, though the utility is unique among siblings.

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

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

With no annotations, the description carries the full burden. It discloses the multi-file bundle, always-run-as-container behavior, required root index.html, and the returned URL opening an editor/preview UI. It doesn't cover authentication or error/overwrite behavior, but the core behavioral contract for a create tool is well stated.

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 compact sentences that are front-loaded with the core action, then differentiate from a sibling, then clarify preview behavior. Every clause 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 complex 6-parameter tool with no annotations, the description plus the detailed schema cover purpose, validation rules, file constraints, and returned URL behavior comprehensively. The presence of an output schema means return-value details need not be in the description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining how files reference each other and why index.html is required as the entry point, which goes beyond the raw schema. It doesn't enumerate each parameter, but the schema already does so thoroughly.

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 'Save a multi-file artifact group', clearly naming the verb and resource. It explicitly distinguishes this from save_to_hypervault (single file), making the tool's unique scope unmistakable.

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 contrasts with save_to_hypervault as the single-file alternative, and explains that a group is for a whole project bundle of files run together. This gives clear when-to-use and 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 transparency burden. It discloses that one call creates both a data artifact and a board page, that the data artifact is not meant for humans, and that the board is 'versioned'. It could mention permission or conflict behavior, but for a creation tool this is strong disclosure.

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

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

The description is concise and front-loaded: purpose first, then artifact mechanics, then usage guidance. Every sentence provides distinct value, with no redundancy or filler.

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

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

Given the tool's complexity (dual artifacts, 5 params, output schema) and lack of annotations, the description fully covers the key context: what is created, what the deliverable is, how to use it, and how it relates to sibling tools. The output schema covers return details, so no need to describe those.

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

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

Schema coverage is 100% with good per-parameter descriptions, so the baseline is 3. The tool description adds strategic usage context for the `tasks` parameter (seed with plan up front), which enriches semantics beyond 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 tool creates a 'universal task board' and explains it produces two artifacts: a JSON data artifact and an interactive board page. It explicitly names the deliverable (`board.url`), which distinguishes it from sibling task tools like `task_create` and `list_task_boards`.

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 explicit when-to-use guidance: 'Use this at the start of any multi-step piece of work the user will want visibility into.' It also advises seeding with tasks rather than creating an empty board, and references other task_* tools, implicitly distinguishing this from incremental task creation.

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 bears full responsibility. It discloses permanence, immediacy, irreversibility, the effect on share/preview URLs, and removal of graph connections. This is thorough behavioral disclosure for a destructive 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 brief, front-loaded with the core action, and every sentence adds value. It packs necessary warnings and usage guidance into just a few lines without 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?

Given the simple parameter structure and presence of an output schema, the description fully covers the operation's purpose, consequences, and usage prerequisites. It leaves no important behavioral 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?

The schema covers the single parameter 'slug_or_id' with 100% description coverage, including format examples. The tool description adds no new parameter semantics beyond reinforcing that the value can come from list_artifact_groups, so baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Permanently delete an artifact group from the user's HyperVault.' It clearly distinguishes from siblings like create_artifact_group, read_artifact_group, and list_artifact_groups by defining the destructive scope and consequences (URL stops working, graph connections removed).

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

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

Explicitly instructs to 'Use list_artifact_groups first to find the right one' and warns to 'only delete when the user clearly asks.' This provides strong usage context and excludes accidental deletion, which is essential for a destructive tool.

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

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

With no annotations provided, the description fully shoulders the burden of disclosing side effects: deletion is immediate and irreversible, the share URL stops working, and graph connections are removed. This is rich, honest behavioral disclosure.

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 paragraphs: the first states the purpose, the second adds critical behavioral caveats. Every sentence earns its place with no redundancy or fluff.

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

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

For a one-parameter destructive tool, the description covers purpose, usage preconditions, irreversibility, and side effects. An output schema exists, so return-value details are not required. It is fully complete for its complexity.

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

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

Schema coverage is 100% and the parameter description already includes an example. The tool description adds no extra parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Permanently delete') and names the resource ('artifact from the user's HyperVault'), clearly distinguishing it from siblings like delete_artifact_group. The first line immediately states the core action without ambiguity.

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

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

Explicitly instructs to use list_my_vault_items first and to delete 'only when the user clearly asks', setting clear when-to-use and when-not-to-use context. This goes beyond a generic description and provides actionable 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 burden. It discloses a key failure mode (fails if path doesn't exist) and the replace semantics. It doesn't mention reversibility or permissions, but for a simple replacement tool with an output schema, this is adequate behavioral disclosure.

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 purpose, critical caveat in second sentence. No filler words; 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?

For a 3-param tool with an output schema, the description covers purpose, usage distinction, failure mode, and a special case (index.html). It's complete without needing return value details thanks to the output 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 100%, giving baseline 3. The description adds meaning by noting the path must refer to an existing file and that content fully replaces old content, plus the index.html twist. This goes slightly beyond the schema's descriptions.

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 ('Replace') and states the resource ('content of an existing file in an artifact group'), clearly distinguishing it from sibling add_artifact_group_item which creates a new file. The mention of index.html further anchors the purpose.

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

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

Explicitly says 'Fails if no file exists at that path yet — use add_artifact_group_item to create one', giving a clear when-to-use vs alternative. Also notes this is how to update index.html, providing concrete 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 full burden and does well: it discloses that changes are update commits, history is preserved, content edits re-derive summaries and auto-tags, and knowledge-graph links are included in the same commit. This gives a rich picture of side effects without requiring the user to infer them from schema or annotations.

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

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

The description is two sentences long, front-loaded with the primary action, and each clause adds critical information: commit behavior, history preservation, summary/tag re-derivation, and KG links. No wasted words.

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

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

Given the tool's complexity (6 params, no annotations) but with an output schema present, the description covers the key non-obvious aspects: safety (never overwrites history), side effects (re-derives summary, auto-tags), and the relationship to memory_history. This is sufficient for an agent to correctly invoke the tool and understand its behavioral footprint.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it explains that content edits trigger summary re-derivation and auto-tag merging, and that new knowledge-graph links ride in the same commit. This enriches the semantic understanding of the 'content' and 'tags' parameters beyond their simple 'New content' and 'Replacement tag list' descriptions.

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 ('Edit a wiki page') and the resource (memory), and distinguishes itself by emphasizing the update-commit behavior and non-destructive nature, which differentiates it from sibling tools like memorize or forget_memory. It also mentions memory_history for revisions, reinforcing its specific role.

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

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

The description provides clear context: edits are committed and never overwrite history, and it points to memory_history for viewing revisions, which implicitly indicates when to use that alternative. However, it does not explicitly contrast with memorize/forget_memory or state explicit 'when to use' conditions beyond the basic action.

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 behavioral context. It discloses the hidden meta tag mechanism, confirms it works on vanity-subdomain links, and illustrates how the returned prompt can be used. This goes beyond the input schema and provides a clear mental model of the tool's behavior.

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

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

The description is three sentences, with the primary purpose front-loaded. It then provides background context and a usage example. Every sentence earns its place, with no redundancy or fluff. The length is appropriate for the tool's simplicity.

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

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

The tool has only one parameter, the schema covers it fully, and an output schema exists. The description covers the purpose, when to use it, the underlying mechanism, and an example of how to use the result. There are no significant gaps in understanding or invocation.

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

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

The input schema already covers the single 'url' parameter with 100% coverage, providing an example. The description adds extra semantic meaning by clarifying that vanity-subdomain links are also valid, which expands the allowed URL forms beyond the schema's example. This additional context justifies a score above baseline.

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

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

The description starts with a specific verb 'Extract' and a clear resource 'original source prompt from a HyperVault artifact URL'. This clearly distinguishes it from sibling tools like read_artifact or write_artifact, which deal with entire artifacts. The purpose is unmistakable and not a tautology.

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 explicitly states when to use the tool: 'Call this when the user shares a HyperVault link... and you want to understand or iterate on the artifact.' It provides a concrete scenario and example response. However, it does not mention when not to use it or reference alternatives, which would push it to a 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?

With no annotations, the description discloses key behavioral traits: the deletion is a commit (recoverable), knowledge-graph links are removed, and the page stays in history. This goes beyond a raw 'delete' statement and helps the agent understand 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?

The description is two sentences, front-loaded with purpose and followed by usage and side effects. No trivial words 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 destructive tool with existing schema and output schema, the description covers what it does, when to use it, and important behavioral consequences. It is complete enough to guide correct invocation without ambiguity.

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

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

The input schema covers both parameters with descriptions (100% coverage), and the description doesn't add further parameter-level semantics. The baseline of 3 applies because schema provides the necessary details.

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 (delete) and resource (one memory from the user's wiki), and notes it's recorded as a delete commit. This distinguishes it from sibling tools like edit_memory, memorize, and recall.

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 'Only call this when the user explicitly asks to forget or delete a memory,' providing a crisp trigger condition. It also describes the restoration path via mind_revert, effectively guiding the agent on when to use and when to consider that alternative.

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 discloses the return format and ordering (newest first), which is useful. However, it does not explicitly state that the operation is read-only or mention any potential limitations like pagination or empty results, though the verb 'List' makes this largely implicit.

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

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

The description is concise and well-structured: it leads with the primary purpose, then gives usage context, and ends with a clear return format. Every sentence contributes to understanding without 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 zero-parameter list operation, the description is complete: it states the purpose, gives usage guidance, and enumerates the return fields and order. Even though an output schema exists, this textual description reinforces the essential details, making the tool self-contained.

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 schema coverage is 100% and the baseline is 4. The description correctly adds no parameter detail, as there is nothing 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?

The description uses a specific verb (List) and identifies the resource (artifact groups) with scope (user's HyperVault). It clearly distinguishes from siblings by focusing on listing all groups versus reading/creating/deleting individual ones.

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 states when to use the tool: before creating a new group to avoid duplicates, or to find a slug for other operations. It names related tools (read_artifact_group, add_artifact_group_item) as consumers of the slug, providing clear context for selection.

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

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

No annotations are provided, so the description carries the full burden. It discloses ordering (newest first) and content scope (summary/tags, not full content), providing useful behavioral context. It doesn't explicitly state it's read-only, but 'list' strongly implies that.

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 succinct sentences: the first states the action and ordering, the second gives usage guidance and content details. No wasted words, well front-loaded.

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

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

For a simple list tool with one optional parameter, an output schema, and no annotations, the description covers purpose, content, and usage context. The branch parameter is documented in the schema, and return details are described in the text.

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 for the single 'branch' parameter is 100%, including its default and optionality. The description adds no extra meaning about the parameter, so the baseline of 3 applies.

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

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

The description clearly states the tool lists everything in the user's private memory wiki, newest first. It distinguishes from sibling tools like recall by noting entries carry only summary and tags, not full content, making it a broad overview tool.

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 'Useful for a broad look at what the user has memorized before deciding what to recall in detail', giving context and naming recall as the alternative for detailed retrieval. The note about 'not the full content' also tells when not to use it.

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

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

No annotations are provided, so the description carries the burden. It discloses the return structure (dict with items list of fields) and ordering (newest first). It does not mention error cases or side effects, but for a simple list operation this is solid coverage.

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 appropriately sized, front-loads the main action, and uses a structured 'Returns:' section. Every sentence earns its place: purpose, usage context, and return format. No wasted words.

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

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

The tool is simple with 0 params and an output schema exists. The description fully covers what it does, why use it, and what it returns, including field names and ordering. 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?

There are zero parameters, so schema coverage is trivially 100%. The baseline for 0 params is 4, and the description doesn't need to explain parameters since none exist. It adds no parameter info, but none is needed.

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

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

The description clearly states the tool lists artifacts in the user's HyperVault, using a specific verb and resource. It distinguishes itself from siblings like list_artifact_groups by focusing on vault items, not groups.

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 states when to use: before saving to avoid duplicates, and for linking via save_to_hypervault's connect_to parameter. Names a specific sibling alternative, providing clear context without needing 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 discloses the read-only 'List' nature, explains the purpose of joining an existing board, and documents the return format (dict with boards and schema URL). It does not explicitly state 'no side effects' or permissions, but the wording strongly implies a non-mutating lookup.

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 tightly structured: one sentence for purpose, one for usage guidance, and a brief return summary. Every sentence earns its place, with no fluff 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?

For a simple no-argument list tool with an output schema, the description is complete. It explains why to call it, when to call it, and what it returns. The scope ('user's existing task boards') is clear, and it correctly positions the tool against create_task_board.

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 the baseline is 4. There is nothing for the description to add beyond what the empty schema already conveys.

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 ('List the user's existing task boards') and clearly distinguishes from sibling create_task_board by noting it avoids creating a duplicate. The phrase 'so you can join one instead of creating a duplicate' clarifies the intended operation.

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 states when to call: 'at session start when the user refers to ongoing work... and you don't already have the project id.' This provides a clear trigger condition and implies when not to use it, while also contrasting with creating a new board.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It discloses that the backend auto-titles, auto-tags, summarizes, and links memories to the knowledge graph, and that memories are private. It does not cover potential side effects like duplicate handling, but this is a strong baseline.

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 four sentences long, front-loaded with the core action, and every sentence contributes essential information: what it does, when to call it, how it behaves, and its privacy guarantee. No waste 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?

Given the rich input schema, presence of an output schema, and a sibling ecosystem of memory-related tools, the description fully covers the tool's purpose, trigger conditions, backend behavior, and data privacy. It does not explain return values, but the output schema satisfies that need.

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 has 100% descriptive coverage, with each of the six parameters explained in detail. The description complements this by noting that the backend auto-generates titles and tags, which reinforces the optionality of those parameters and adds context about the 'private wiki' environment.

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 and resource: 'Store a chunk of context in the user's private memory wiki'. It clearly distinguishes this from sibling tools like recall and list_memories by framing it as the creation/write operation. The mention of automatic processing and privacy further narrows its scope.

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 explicit triggers ('whenever the user says "remember this", "memorize this"') and semantic contexts (sharing a decision, preference, or insight). It also hints at an exclusion by noting memories are private, suggesting this is not for public content, though it doesn't name specific alternative tools.

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

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

With no annotations, the description discloses key behaviors: revisions are listed newest first, each carries commit metadata (message, author, branch, time), and it's a read operation. This goes beyond the schema's parameter definitions.

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 main purpose. The second sentence adds valuable context about revision contents and the revert integration without 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?

The tool has an output schema and full parameter coverage. The description explains the nature of the output (commit info), ordering, and next-step integration with mind_revert. It's sufficient for a history-read tool, though it doesn't explicitly mention pagination or default limits (schema does).

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

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

Schema coverage is 100%, so the baseline is 3. The description doesn't add significant parameter-level detail; the schema already documents memory_id, full, and limit clearly.

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: 'Every revision of one wiki page... its edit history.' It clearly distinguishes from siblings like recall or list_memories by focusing on revisions and even links to mind_revert for restoration.

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 implies when to use this tool: when you need edit history of a specific memory. It also provides a workflow pointer to mind_revert for restoring old versions. However, it doesn't explicitly contrast with alternatives like artifact_history or list_memories, so not a 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?

With no annotations, the description effectively discloses a key behavior: the branch isolates changes from the source until merged. It also provides naming constraints. However, it does not explain what happens to the current working context or whether the branch becomes active, which is a minor 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?

Two sentences: the first explains the core function with a clear analogy, the second specifies naming constraints. No redundant information is present.

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

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

For a simple branch-creation tool with only two parameters, the description covers the essential purpose, isolation behavior, and naming rules. The output schema handles return-value documentation, so the description is complete enough.

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 already describes both parameters clearly. The description adds value by specifying the exact allowed character set and maximum length for branch names, going beyond the schema's basic 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?

The description explicitly states the tool creates a branch (fork) of the wiki, isolating edits, memories, and forgets until merge. This clearly distinguishes it from sibling operations like mind_merge or mind_revert.

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 usage is clearly implied: use this to create an isolated branch for changes. It does not explicitly list when not to use it or alternatives, but the context of the version-control-like suite makes the intended use obvious.

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 must disclose behavioral traits. It does indicate a read-only listing operation and 'live memory counts' (suggesting dynamic values), but it does not mention potential errors, permissions, or ordering. For a simple read tool this is acceptable but not exhaustive.

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

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

The description is concise, front-loaded with the purpose, and includes a compact return format. Every sentence adds value and there is 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 list tool with an output schema, the description is complete. It covers what the tool does and the nature of the return data, and the output schema handles detailed return value documentation.

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 the description appropriately omits parameter details. Baseline for a 0-parameter tool is 4, as there is nothing to document.

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

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

The description clearly states it lists the user's mind branches with live memory counts. The verb 'list' distinguishes it from sibling operations like mind_branch (create/switch) and mind_state, making the purpose unambiguous.

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

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

The description implies usage when one needs to enumerate branches, but it does not explicitly mention when not to use it or suggest alternatives. It lacks the explicit guidance seen in higher-scoring examples, but the tool's simplicity makes the usage fairly 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 provided, the description carries the full burden. It discloses that without memory_id the diff includes added/changed/removed memories with content hunks and links, and with memory_id it returns just that page's diff. This gives a clear mental model of the operation's output, though it doesn't mention error conditions or explicitly confirm side-effect-free behavior.

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

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

The description is two sentences: the first states the core purpose with an illustrative example, and the second concisely enumerates behaviors for both usage modes. No wasted words; it is front-loaded and easy to parse.

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

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

The description covers the tool's purpose and the two operational modes, and the output schema handles return value details. It would be slightly more complete with an explicit read-only note, but the diff semantics make that clear. Essentially self-sufficient for selection and 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 schema already documents all three parameters with descriptions, so the baseline is 3. The description adds meaning by explaining what the refs can be (branch names, commit ids, timestamps) and clarifying the effect of memory_id on the diff scope, going slightly beyond the schema's 'diff a single memory instead of the whole graph.'

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 diffs the user's mind between two refs, specifying ref types (branch names, commit ids, timestamps) and the scope of output. It differentiates from sibling tools by focusing on diffing memory state, and further clarifies distinct behaviors for whole-graph vs. single-memory diffing.

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 a concrete usage example ('what changed in my memory since last week?') and explains when to use the optional memory_id parameter (single page diff) vs. not (whole graph). However, it does not explicitly compare to similar sibling tools like memory_history or mind_log, nor state when not to use it.

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

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

The description discloses behavioral traits such as 'newest first' and 'per-commit change counts and authorship.' However, with no annotations provided, it does not explicitly state that the operation is read-only or has no side effects, which is a notable omission for a tool of this kind.

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

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

The description is a single sentence that is both concise and front-loaded with the 'git log' metaphor. It efficiently conveys purpose and key details without 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?

The tool is simple with two optional parameters and an output schema. The description adequately explains what the tool does, but it could briefly mention the effect of the limit parameter or explicitly state read-only behavior. Overall, it is sufficient for the tool's complexity.

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

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

Schema coverage is 100% and each parameter (limit, branch) is described in the schema. The tool description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: 'git log for the user's mind: the branch's commit history, newest first, with per-commit change counts and authorship.' It specifies the resource (branch commit history) and output details, effectively distinguishing it from sibling tools like mind_diff or mind_state.

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 commit history but does not explicitly state when to use this tool versus alternatives. It lacks exclusions or comparisons with sibling tools, so guidance is only implicit.

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 fully discloses the merge strategy (three-way from common ancestor), automatic merge behavior for one-sided changes, set-wise link merging, failure mode with conflict list (base/ours/theirs snapshots and hunks), and the exact resolution format. It also gives guidance on when to involve the user.

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-loaded with the purpose, then each subsequent sentence provides essential details about conflict behavior and resolution. No redundant or filler content; the length is appropriate for the complexity.

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 addresses the merge process, conflict handling, resolution workflow, and user guidance, making it complete for a complex operation despite lacking 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?

Schema coverage is 100%, so baseline is 3. The description adds concrete examples for the resolutions parameter (e.g., [{"memory_id": "...", "resolution": "theirs"}] or a hand-merged object), going beyond the schema's generic array-of-objects description. It also clarifies the merge semantics for source/target via the common ancestor.

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+resource: 'fold a branch into a target (default main) with a three-way merge from their common ancestor.' This clearly distinguishes it from sibling tools like mind_branch, mind_diff, and mind_revert.

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 clear context for the merge operation and conditional guidance for conflict resolution ('resolve by calling again with resolutions', 'Relay conflicts to the user when the choice isn't obvious'). No explicit comparison to alternative tools or exclusions, but the scenario 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, the description carries the full burden of behavioral disclosure. It conveys a crucial non-destructive guarantee ('History is never rewritten: the restore lands as a new commit') and notes the ability to undelete 'forgotten' memories, which are important behavioral traits.

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

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

The description is three tight sentences. Each sentence earns its place: the first states the main action, the second explains the immutable-history behavior, and the third directs to a prerequisite. No redundancy or fluff.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description sufficiently covers the key behavioral aspects (new commit, undeletion) and points to the source for revision IDs. No critical information seems 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 schema descriptions already cover all three parameters (100% coverage), so the baseline is 3. The description adds value by clarifying that memory_id can refer to a 'forgotten' (deleted) memory and that revision_ids come from memory_history, which enriches the meaning of those parameters beyond 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 primary action: 'Restore a memory to an earlier revision' with a specific verb and resource. It also highlights a special capability ('including undeleting a forgotten one') and points to a sibling tool ('Find revision ids with memory_history'), distinguishing it from related tools like edit_memory or mind_merge.

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 gives clear context for when to use the tool (when restoring to a previous revision) and explicitly instructs to find revision ids via memory_history, which is a prerequisite. However, it does not mention alternatives or exclusions, so it stops short of a 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 itself must convey behavior. It indicates a read-only reconstruction of a past state ('as it stood'), which is useful context. However, it does not explicitly state side-effect-free behavior, permissions, or error conditions, leaving some gaps.

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

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

The description is a single sentence that instantly communicates the tool's purpose without fluff. It is front-loaded with the key metaphor and specifies scope, making it highly efficient.

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 available, the description does not need to elaborate return values. It covers the primary functionality (retrieving a full wiki snapshot at a point) and is complemented by schema descriptions for parameters. It doesn't address edge cases, but that's not expected for a well-specified tool.

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

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

The schema fully describes both parameters ('at' and 'branch') with clear descriptions. The tool description adds no parameter-specific information, but the schema already provides sufficient guidance, so the baseline score of 3 applies.

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

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

The description uses a clear metaphor 'Time-travel' and specifies the resource: 'the whole wiki (memories + links) as it stood at a commit, branch head, or moment in time.' This clearly distinguishes it from sibling tools like mind_diff (which compares states) or memory_history (which focuses on a single memory).

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 implicitly communicates a use case: retrieving a historical snapshot of the entire wiki. However, it does not explicitly mention alternatives or when not to use it. The context is clear enough that an agent could infer the correct scenario, but there are no exclusionary guidelines.

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 clearly reveals that the returned value is the editable source, not the rendered chrome, and that the version parameter can read past iterations. This is a meaningful behavioral disclosure, though it doesn't explicitly state non-destructive/read-only or error behavior, which is implied.

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

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

The description is three sentences: a clear purpose, a crucial nuance about the returned format, and a concrete workflow. It is front-loaded and 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?

The tool is simple with two well-documented parameters and an output schema. The description covers the key distinction between editable source and rendered output, making it sufficiently complete for an agent to select and invoke correctly.

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

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

The schema already provides 100% coverage with detailed descriptions for ref (slug/URL/vanity domain) and version (from artifact_history). The tool description adds little beyond the 'editable source' context, so the baseline 3 applies.

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

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

The description uses a specific verb ('read') and resource ('source of one of the user's artifacts'), and clearly differentiates from siblings by explaining it returns the editable source (React/JSX or HTML), not the wrapped page. It also positions itself against write_artifact and artifact_history, making its purpose unmistakable.

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 tells the agent to pair with write_artifact for edits and provides a read-modify-write workflow. It also hints at using artifact_history to obtain a version id for past iterations, giving concrete context for when to use the version parameter.

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 conveys a read-only operation and indicates the return includes full file set and metadata, but it does not address error behavior, permissions, or any side effects. This is minimal but not misleading, meriting an average score.

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 efficiently states the action, scope, and a use case without any wasted words. Every word earns its place, and it is perfectly concise.

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

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

For a simple read tool with one parameter and an output schema, the description is complete enough. It clarifies the scope ('full file set and metadata') and provides a practical workflow hint. It could mention error cases or read-only nature explicitly, but the context signals and schema compensate, warranting a 4.

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

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

The input schema already has 100% coverage with a detailed description of the 'ref' parameter, so the baseline is 3. The tool description adds no additional parameter semantics beyond what the schema provides, staying at that baseline.

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 reads an artifact group's full file set and metadata, using the specific verb 'read' and resource 'artifact group'. It also distinguishes from siblings by mentioning the context of iterating before calling edit_artifact_group_item, making its purpose unmistakable.

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 gives clear usage context by stating 'so you can iterate on it (e.g. before calling edit_artifact_group_item)', implying when to use this tool. However, it does not explicitly exclude alternatives or mention when not to use it, so it falls short of a 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?

With no annotations, the description fully discloses behavior: it combines full-text search with relevance scoring, specifies that top matches return exact content while others return summaries, and explains that linked memory titles are included. This goes beyond a simple 'search' and informs the agent about result granularity and graph traversal.

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

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

The description is three sentences, each earning its place: purpose is stated first, then a usage example, then output behavior. No redundant information or filler.

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

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

Given the tool's simplicity (2 params) and the presence of an output schema, the description is complete enough. It covers what the tool does, when to use it, and what to expect in results, without needing to restate return fields. It is well-rounded and tightly written.

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

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

Schema description coverage is 100%, with query and branch both documented. The description adds a natural-language example but does not meaningfully extend the schema's definitions; baseline 3 is appropriate because the structured data already explains parameters.

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

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

The description clearly states the tool's verb and resource: 'Search the user's private memory wiki with a natural-language query.' This is specific and distinguishes it from sibling tools like list_memories (which would list all memories) or memorize (which writes).

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 a concrete use case ('what did I say about the Rust borrow checker last month?') and says 'Use this to answer questions like...', which gives clear guidance on when to invoke it. It does not explicitly list alternatives or exclusions, but the context is clear enough for an agent to choose it for semantic memory search over list/forget tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a key limitation (root index.html exclusion) and hints at the tool's alterative usage, but does not disclose side effects such as permanence of removal or error behavior for missing paths. Still, the disclosed restriction is valuable context beyond the basic action.

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

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

The description is concise and front-loaded. The first sentence immediately states the purpose, followed by a focused limitation and alternatives. No redundant 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?

The tool is simple, with full schema parameter coverage and an output schema present. The description covers the main usage scenario and key exclusion (root index.html), which is sufficient for most calls. Missing details like error handling for non-existent paths are minor given the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by referencing 'root index.html', which clarifies that the 'path' parameter is a file path and that there is a special entry-point file. This enriches the schema's simple descriptions.

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 'Remove a file from an artifact group,' specifying the exact action and resource. It distinguishes itself from sibling tools by explicitly noting that the root index.html cannot be removed this way and directing to edit_artifact_group_item or delete_artifact_group as 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 provides explicit when-to-use and when-not-to-use guidance: it states the root index.html can't be removed, and suggests replacing its content or deleting the whole group. This directly addresses the main decision point for selecting this tool over alternatives.

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. It discloses key behaviors: permanent saving, shareable URL creation, and automatic wrapping of React/JSX content into a standalone page. It does not mention immutability defaults or versioning, but those are covered in the parameter schema, so the description adds meaningful behavioral context.

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: the first states the core purpose and the second adds a key automation feature. It is front-loaded, concise, and 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?

Despite the tool's complexity (9 parameters, output schema), the description plus the rich parameter schema provide sufficient context for correct usage. The description covers the core action and a notable behavior (JSX wrapping), while the schema handles remaining details. It could be more explicit about mutable documents, but overall it is complete enough.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds minor context by mentioning that a bare React component can be passed and will be auto-wrapped, which relates to 'content' and 'type', but it does not extend meaning for other parameters beyond 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 uses the specific verb 'Save' and identifies the resource 'HyperVault' and the outcome 'get back a shareable URL'. It also lists example artifact types (HTML, React/JSX, report, game) and distinguishes itself from sibling tools by emphasizing permanent storage and automatic JSX wrapping.

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 saving new artifacts and highlights automatic JSX detection, but it does not explicitly contrast with alternatives like write_artifact or state when not to use this tool. The guidance is inferred rather than explicit.

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

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

With no annotations provided, the description carries the full transparency burden and excels. It discloses the lock mechanism (60 min default, 24h max, renewal on re-claim), the 409 error behavior, the effect of `force`, and the semantics of `release`. It also explains the agent_name requirement. This goes far beyond a typical description and gives the agent complete behavioral expectations.

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

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

The description is well-structured: a punchy first sentence states the core idea, followed by a compact paragraph of critical mechanics. Every sentence adds value—lock behavior, 409 handling, force guidance, and release—without fluff. It is appropriately sized for the tool's complexity.

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

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

Given the tool's medium complexity (8 params, 3 required) and the presence of an output schema, the description covers all critical operational aspects: when to claim, lock semantics, error handling, force usage, and release behavior. It provides enough context for an agent to safely and effectively invoke the tool without needing to inspect siblings or infer undocumented behavior.

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

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

Schema coverage is 100%, so a baseline of 3 is warranted. The description adds meaningful context for key parameters: lock_minutes (default 60, max 1440), force (only when holder gone), release (hand back), and agent_name (required for meaningful claims). This elevates it above baseline but the schema already describes each parameter well, so it doesn't reach 5.

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 identifies the tool's function: 'Claim a task before you start it — a lock plus assignment.' It specifies the resource (task) and the verb (claim), and distinguishes itself from siblings by focusing on the claiming/locking workflow rather than creation or completion. The behavioral details (set to in_progress, assign, lock) reinforce the purpose.

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

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

Explicit guidance is provided: 'Claim deliberately: prefer tasks already assigned to you or unassigned, and never silently take another agent's live claim.' It also states when to use `force` ('only when the holder is clearly gone') and when not to (expired locks are claimable without it). The description covers both appropriate context and exclusions clearly.

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 concrete side effects: setting status to done, progress to 100, releasing the lock, and making the task un-reclaimable. This goes beyond the schema and provides meaningful behavioral expectations.

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

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

The description is concise and front-loaded with the core purpose, followed by usage timing, note requirement, and a warning. Every sentence earns its place without redundant phrasing or excessive length.

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

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

The description covers the main effect, recommended usage timing, and a key constraint (cannot re-claim). With an output schema and fully documented parameters, the missiing details (e.g., expected_version behavior, return type) are not critical. It provides enough context for safe invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only a minor hint about the note ('Pass a closing note saying what landed'), but the schema already explains it as the closing note appended to the thread. No additional parameter semantics are provided.

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

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

The description opens with 'Mark a task done: status done, progress 100, lock released, in one call,' which specifies the exact verb, resource, and resulting state. This clearly distinguishes it from sibling tools like task_update or task_claim by condensing multiple updates into a single completion action.

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 gives explicit timing guidance ('Complete a task as soon as it's actually finished — don't batch completions at the end of a session') and a warning ('A done task can't be re-claimed'). It does not name alternative tools, but the context clarifies when to use this tool over a general update.

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. It discloses a key behavioral trait: 'a task you create here shows up on the user's board immediately, which is the point.' This adds context beyond the schema. However, it does not explicitly mention potential conflicts, permissions, or reversibility, relying on the schema's expected_version description for conflict behavior. Still, the immediate-visibility disclosure is valuable.

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 and front-loaded. The first sentence states the core purpose, and the second paragraph provides usage guidance. Every sentence earns its place with no fluff 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?

Given the tool's complexity (12 parameters) and the presence of a detailed schema (100% coverage) and output schema, the description provides sufficient context. It communicates the primary purpose, immediate effect, and usage distinction. It doesn't elaborate on return values or all params, but the schema covers those. The only minor gap is not mentioning the conflict behavior directly, though the schema references it. Overall, it is adequately complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific semantics beyond the schema; it only references `tasks` in create_task_board, not this tool's own parameters. Thus, the schema already does the heavy lifting, and the description adds no extra value here.

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 adds a task to an existing board, using the specific verb 'Add' and resource. It distinguishes itself from create_task_board by noting this tool is for mid-session work on an existing board, while create_task_board seeds known work. This is a specific, non-tautological purpose.

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

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

The description explicitly says when to use this tool ('use this for what comes up mid-session') and when to prefer an alternative ('Prefer seeding known work through create_task_board's `tasks` argument'). This is clear guidance on usage versus alternatives, going beyond mere 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 takes on the full burden of explaining behavior. It discloses the lightweight response shape when using since_version ('{unchanged: true, version}') and describes the scope of data returned. It does not cover auth requirements or error conditions, but for a read operation this is quite transparent.

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

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

The description is concise and well-structured: a clear purpose sentence followed by actionable usage guidance. Every sentence contributes value, 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?

Given the presence of an output schema (which likely details the response structure), the description focuses on the critical usage patterns: full read vs. cheap poll. It also includes context about when to poll (tool boundaries) and what the user actions might affect. This is comprehensive for a read/list tool.

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

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

The input schema already covers both parameters with descriptions (100% coverage). The description adds meaningful context for since_version, explaining its purpose and the response optimization, which goes beyond the schema's 'The version you last saw.' It does not add extra meaning for project, but that is adequately described 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 starts with a clear, specific verb and resource: 'Read a task board's full list' and enumerates the contents ('every task with its status, assignee, lock, and note thread'). This distinguishes it from sibling tools like tasklist_summary, which likely provides a condensed view.

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

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

The description explicitly tells when to use the tool: 'Read this at session start, and re-poll it at tool boundaries' and explains why. It also gives guidance on the since_version parameter for efficient polling. However, it does not mention when not to use it or name alternatives (e.g., tasklist_summary), so it falls short of a perfect 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?

With no annotations, the description carries the full burden. It discloses a key behavioral trait: this tool returns a rollup/summary without pulling every task, indicating a lighter, aggregated operation. It also implies read-only via 'Get', but it does not explicitly state side-effect-free or mention auth/rate limits, which are less critical for a summary endpoint.

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 remarkably concise: two sentences, the first stating the core purpose, the second giving usage guidance and a rationale. Every sentence adds value, and the most important information is front-loaded.

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

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

Given that the tool has one parameter, an output schema, and a clear description of what it does and when to use it, the agent has everything needed to select and invoke the tool correctly. The description fully covers purpose, usage, and the key behavioral nuance (rollup vs full list).

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

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

Schema coverage is 100%, with the single parameter 'project' well-described as 'The board's project id, data slug, or URL.' The description does not add further parameter detail, but that is unnecessary when the schema is fully self-explanatory, so baseline 3 is appropriate.

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

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

The description clearly states a specific action: 'Get a board's rollup' and enumerates what's included (counts, progress, epics, who's holding what). It distinguishes from tasklist_get by noting it avoids pulling every task, making the tool's purpose unmistakable.

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 explicitly says 'Prefer this over tasklist_get' and provides concrete use cases (reporting status, deciding what to pick up next) plus a rationale (a large board's full list is token-heavy). This directly guides when to use this tool over an alternative.

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 the burden. It discloses key behaviors: only passed arguments change, note appends, metadata merges. This is meaningful for a mutation tool, though it omits details like lock release or concurrency handling (which appear in schema descriptions).

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 paragraphs, first sentence is a crisp purpose. The second paragraph is slightly verbose but earns its place by explaining usage cadence and key behaviors. No fluff.

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

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

With 14 parameters fully covered by the schema and an output schema present, the description need not enumerate fields. It provides usage context and critical behavioral semantics, making it sufficiently complete for the complexity.

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

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

Schema coverage is 100% and parameter descriptions are detailed. The main description adds no new parameter information beyond repeating that note appends and metadata merges (already in schema). Baseline 3 is appropriate.

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

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

The description clearly states 'Patch one task on a board' with a specific verb and resource, and lists example fields. This distinguishes it from siblings like task_create, task_claim, and task_complete.

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 strong guidance on when to use: 'Push every meaningful change the moment it happens' and explains why (board polls, liveness). It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for a 4.

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 fully discloses key behaviors: in-place update (URL never changes), versioning with artifact_history and revert, auto-detection of React/JSX, and no-op behavior for identical content (unchanged: true). This exceeds expectations for a write 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 well-structured: an opening tagline, followed by behavioral details, and ended with a concrete usage loop. Every sentence adds value, and the content is organized logically without 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?

Given the complexity (5 parameters, no annotations) and the existence of an output schema, the description is complete enough. It covers prerequisites, limitations, edge cases, and the typical workflow, leaving no ambiguity 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 schema covers 100% of parameters with detailed descriptions, so the baseline is 3. While the tool description reinforces some parameter behaviors (e.g., content replacement, message in history), it adds no new parameter-specific meaning beyond 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 opens with a clear, specific verb and resource: 'Write a new iteration of a *mutable* artifact' and uses the git commit metaphor to clarify the versioning nature. It also distinguishes from siblings like read_artifact and artifact_history by focusing on mutation and versioning.

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 explicitly states when this tool is applicable: only for artifacts saved with mutable=true, and it warns that immutable artifacts return an error with guidance to re-create as mutable. It also provides a typical usage loop with read_artifact, making the intended workflow clear.

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