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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description isn't expected to repeat that. It adds non-obvious behavior: permanent-retention entries are skipped, filters combine as AND, older_than_hours evaluates against memory_at, and required permission is 'memory:write or full permission'. Those are meaningful traits that go beyond 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?

Seven short sentences, each carrying a distinct fact: effect, recovery paths, filter combinators, retention exception, restore tool, permission, and call target. The playbook_id clarification is redundant with the schema's own description, but overall it is front-loaded and largely waste-free.

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 6-param mutation tool with no output schema, the description covers the effect, recovery, filter semantics, permission requirement, and the key playbook_id target. It stops short of describing what a call returns or how partial/failed matches behave, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds a bit beyond the schema – the AND combination rule and the memory_at clock for older_than_hours – but otherwise doesn't need to restate parameter-level meaning. 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?

States a specific verb and resource ('Hide matching memories from normal search and context, retaining them in the longterm tier'), and immediately distinguishes the effect from delete_memory by describing retention and recovery paths. An agent can differentiate it from delete_memory, search_memory, and promote_memory without opening any schema.

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

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

Gives concrete context: how to retrieve archived items (scope='archived', read_memory by key), how filters combine ('AND'), and that promote_memory restores visibility. It doesn't state explicit when-not-to-use conditions or name the alternative tool for irreversible deletion, but the implied usage frame is clear.

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

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

The description discloses that arguments are forwarded as-is and results mirror the connected tool, including side effects in the outside world. This complements the containing annotations (readOnly=false, destructive=true, openWorld=true) by explaining what those flags mean in terms of real-world 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 compact and front-loaded, with the core purpose in the first sentence. It covers essential behavior, permissions, discovery, and exclusions in four short sentences 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 tool's dynamic nature and lack of an output schema, the description adequately covers invocation, side effects, permission requirements, parameter discovery, and limitations. It is not overly detailed but it gives an agent enough context to use the tool safely and 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?

Though the schema already describes all four parameters, the description adds meaningful context by directing users to list_mcp_servers to discover server_id and tool_name, and by explaining that arguments are forwarded as-is. This goes beyond the schema's brief field 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 tool's action: call a tool on one of the playbook's connected MCP or OpenAPI servers. It also distinguishes this tool from connection-management siblings by saying to use create/update/delete_mcp_server instead, making the 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 explicit when-to-use context (calling connected tools) and explicit when-not-to-use guidance with named alternatives for managing connection records. It also tells the agent to use list_mcp_servers to discover server_id and tool_name, covering discovery prerequisites.

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?

Annotations are generic and all false, so the description carries the burden. It explicitly discloses that child rows stay readable, that children are archived to the longterm tier by default rather than deleted, and that memory:write or full permission is required. It does not cover edge cases like existing parent keys, which prevents a 5.

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

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

The description is three sentences, each earning its place. It front-loads the core purpose, adds essential behavioral details, and provides alternative-tool guidance without padding.

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

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

For a tool with 6 parameters and no output schema, the description provides sufficient operational context: when to use it, permissions, alternatives, and default archiving behavior. It does not describe return values, failure modes, or what happens if parent_key already exists, but the schema covers parameter semantics and the key behavioral aspects are present.

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 marginal value for parameters (e.g., confirming playbook_id is a UUID/GUID), while parameter meanings are already well documented in the schema. No compensation needed beyond schema.

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

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

The description clearly states the action: 'Consolidate related memories under a new parent memory with a summary.' It names the specific resource (memories) and explicitly contrasts this tool with archive_memories and delete_memory, making its unique role clear.

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 strong usage guidance: it explains when to use consolidate_memories, and when to use delete_memory ('only when a key should be destroyed') or archive_memories ('move entries to longterm without creating a parent'). It also states the permission requirement and how to pass playbook_id.

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

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

The description discloses the side effect: 'This writes playbook state; it does not by itself invoke remote tools.' It also states the permission requirement, which adds value beyond the annotations (which only indicate readOnlyHint=false, etc.). It does not contradict annotations. Some additional context like failure modes or return behavior is absent, but the core behavioral transparency is strong.

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

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

The description is three sentences, front-loaded with the primary purpose, then side effects and permissions, and finally usage guidance. Each sentence serves a distinct purpose with no redundant or filler content. It is optimally 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?

Given the tool's complexity (7 params, nested objects, no output schema), the description covers the purpose, side effects, permissions, related tools, and target parameter. It does not describe what the return value represents, which would be helpful since there is no output schema, but this is a minor gap. Overall, the description is thorough for a create-type operation.

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 provides descriptions for all 7 parameters (100% coverage), so the description does not need to explain each. It does add a small clarification for playbook_id ('Pass playbook_id as the UUID or GUID of the playbook this call should target'), but this largely reiterates the schema. No significant new parameter meaning is provided beyond what the schema already contains.

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

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

The description clearly states the verb and resource: 'Connect an MCP or OpenAPI server to this playbook by storing its transport configuration.' It explicitly differentiates from siblings by noting it does not invoke remote tools (unlike call_connected_tool) and is for adding a server (unlike list_mcp_servers).

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 usage context: it mentions the required permission (playbooks:write), gives clear alternatives ('Use call_connected_tool to invoke a discovered tool, and list_mcp_servers to inspect connections'), and indicates the targeting requirement for playbook_id. This fully guides the agent on when and how to use the 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?

The description goes beyond the annotations by clarifying the tool's behavior: 'This does not add a second persona; it is a backward-compatible alias that overwrites those fields.' This adds important context about side effects (overwriting) and the alias nature, which is not fully captured by the annotations alone. The permission requirement is also disclosed. No contradiction with 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 concise and well-structured: a single focused opening sentence, followed by clarifications and usage alternatives. Each sentence adds value, and there is 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?

The description covers the tool's purpose, behavioral details, permission requirements, and clear distinctions from related tools. Given the rich annotations and complete schema, this description is fully sufficient for an agent to decide when and how to use it.

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 implies the roles of name, system_prompt, and playbook_id through its main clause, but does not add detailed parameter-level semantics beyond the schema. Since the schema is thorough, this is adequate.

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 purpose: 'Set the playbook's singleton persona name and system prompt.' It specifies the exact resources affected and explicitly differentiates from sibling tools like update_persona and update_playbook, leaving no ambiguity about what this tool does.

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

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

Provides explicit usage guidance: 'Prefer update_persona to change a subset of fields' and 'Use update_playbook only when you also need playbook name, visibility, config, or project instructions.' It also warns against delete_persona unless resetting, and states the required permission level. This is exemplary decision-support.

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 adds important behavioral context beyond the annotations: it states every call inserts a new record (does not upsert by name) and requires playbooks:write or full permission. This goes beyond the bare annotations (e.g., idempotentHint=false) by explaining exactly what that means in operation. Minor gap: does not explain what happens to existing playbook containers or return behavior, but the provided details are genuinely useful.

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 sentences, front-loaded with the core action and resource, followed by non-upsert behavior and an alternative tool recommendation. No filler or redundancy; 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 8 parameters, nested objects, and no output schema, the description gives enough operational context: creation semantics, auth requirement, and when to use an alternative. It doesn't describe the returned value or error/edge-case behavior, which could be slightly richer, but it is largely complete for this tool's complexity and available schema info.

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?

Param descriptions cover all 8 fields (100% schema coverage), so the description does not need to repeat them. It adds a slight conceptual frame by describing the container's purpose, but no parameter-specific enrichment beyond the schema. This is acceptable for a tool with excellent schema documentation.

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 and resource ('Create a new playbook container') and specifies the container's role ('for a singleton persona, skills, and memory'). It clearly distinguishes from update_playbook, and the explicit 'each call inserts a new playbook; it does not upsert by name' makes the create-only scope 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 explicit when-to-use and when-not-to-use guidance: 'Create a new playbook...' plus 'Use update_playbook to change an existing playbook, not this tool.' It also notes the required permission, helping the agent decide if the tool is appropriate for the current 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 all annotations set to false, the description carries the full burden of disclosing behavior. It clearly indicates this is a write operation (creates a run) and adds context about permissions and immediate application. It does not mention idempotency or side effects beyond creation, but the provided information is adequate.

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. Each of the four sentences adds distinct value: purpose, permission, alternatives, and parameter guidance. No fluff or 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?

Given the 3 parameters, no output schema, and simple annotations, the description covers the essential aspects: what it does, when to use it, permissions, and parameter hints. It lacks information about the return value or error cases, but those are not critical for this create-style 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?

Schema coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema: it reiterates that playbook_id should be a UUID or GUID, but this is already in the schema. The mention of 'isolated context and canvas artifacts' gives some semantic context to the context parameter, but not enough to elevate the score.

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

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

The description clearly states the tool's function: 'Create a workflow run so this playbook can be applied immediately.' This is a specific verb+resource combination that distinguishes it from siblings like list_runs, update_run, and delete_run. It also explicitly notes the absence of a get_run, further clarifying its 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 explicitly instructs when to use this tool versus alternatives: 'Use list_runs to inspect existing runs (there is no get_run) and update_run to change status.' It also mentions the required permission ('Requires canvas:write or full permission'), providing clear usage 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?

Annotations already declare readOnlyHint=false and destructiveHint=false; the description goes further by disclosing the permission tiers and the approval workflow that determines whether the skill actually exists. It does not cover failure behavior (e.g. what happens on a name collision or malformed frontmatter) or what the call returns, so it stops short of full 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?

Four sentences, front-loaded with the core action and then permissions, alternatives, and the target identifier. Efficient overall, though the closing playbook_id sentence largely duplicates the schema and could be dropped.

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

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

No output schema exists, and the description never indicates what a successful create returns (e.g. the new skill id) or how to follow up. Everything else an agent needs to invoke the tool correctly — permissions, proposal mode, collision-check workflow, target playbook — is present.

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's only parameter content is restating that playbook_id is a UUID/GUID, which the schema already says verbatim; it adds no syntax, format, or constraint detail beyond the structured fields.

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

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

States a specific verb and resource (create a skill scoped to a playbook) and explicitly separates itself from update_skill and list_skills. An agent can identify this as the creation path without opening a schema.

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

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

Gives the precondition for use (full or skills:write permission), the divergent behavior under skills:propose (saved as pending_review proposal), and routes the agent to update_skill for existing skills and list_skills for collision checks. This is explicit when-to-use plus named 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?

The description discloses the idempotent upsert behavior (repeating plan_key overwrites) and the destructive implication, consistent with the destructiveHint annotation. It also states the permission requirement, adding context beyond 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?

Concise, front-loaded with the core purpose, then usage alternatives, then behavioral notes and permission. Every sentence adds value 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?

Despite no output schema, the description covers purpose, usage, alternatives, behavior, permissions, and targeting. Nested task structure is well documented in schema; description adds the key semantic of overwriting by plan_key.

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 per-parameter descriptions. The description adds minimal param-specific insight beyond what schema provides (e.g., playbook_id as UUID/GUID is already in schema). 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 clearly states the tool creates a hierarchical task plan with a parent plan and child nodes per subtask. It distinguishes from siblings like write_memory (single node) and update_task_status (moving nodes) by focusing on bulk creation.

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 names alternative tools: write_memory for single nodes, update_task_status for status changes, get_memory_tree for inspection. Also mentions upsert/overwrite behavior and the required permission (memory:write/full).

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?

Beyond the annotations (destructiveHint, idempotentHint), the description discloses important behavioral details: the remote server is not shut down, only the playbook's connection record is removed. This adds value by explaining the scope of the destructive action and the permission requirement.

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: it states the core action first, then adds essential context (no remote shutdown, permission, alternative tool, parameter guidance). Every sentence earns its place 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 simple disconnect tool with two parameters and no output schema, the description is complete. It covers purpose, behavioral scope, permissions, alternative usage, and parameter targeting, making it fully adequate 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?

Schema coverage is 100%, so the baseline is 3. The description mentions 'Pass playbook_id as the UUID or GUID' but this simply restates the schema description. No additional semantic value is added for either parameter 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 a specific verb ('Disconnect') and resource ('MCP or OpenAPI server from this playbook'), clearly stating what the tool does. It also distinguishes itself from siblings by clarifying that only the connection record is removed, not the remote server.

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 guidance on when to use this tool versus an alternative: 'Use update_mcp_server to change configuration without disconnecting.' It also states the required permission, giving clear context for usage.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description still adds real value beyond them: permanence including saved history, the required permission scope, and the archive-vs-delete decision. It does not, however, describe failure behavior or what happens to dependent references.

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 sentences, front-loaded with the destructive action. The closing sentence largely duplicates the schema's playbook_id description, which is the only bit of slack in an otherwise tight definition.

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

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

For a two-parameter destructive tool with full annotation coverage and no output schema, the description supplies what an agent needs: permanence, permission requirement, and the safer alternative. Only edge-case behavior (errors, cascading effects) is left implicit.

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

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

Schema description coverage is 100%, so the baseline is 3. The final sentence restates playbook_id's format ('UUID or GUID'), which the schema already documents verbatim, and adds no new syntax or constraint for 'key'.

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?

Specific verb ('Permanently delete') plus resource ('a memory and its saved history'), and it explicitly distinguishes itself from the sibling archive_memories. An agent can select it without opening the schema.

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

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

It names the alternative (archive_memories) and the exact condition that selects it ('To hide an entry while retaining its content'). It also states the precondition (memory:write or full permission).

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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further: it clarifies that despite the 'delete' name, this is not a hard delete, fields are overwritten rather than removed, custom name/system prompt/metadata are permanently replaced and cannot be undone, and the persona_id must equal playbook_id. It also cites the required permission (personas:write or full). This is exemplary behavioral disclosure beyond the structured 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?

Six sentences, each packed with essential information: purpose, semantic nuance, ID constraint, irreversible effects, permission requirement, and alternatives. There is no fluff or repetition; every sentence earns its place. The structure flows logically from what → why → constraints → consequences → guidance.

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 mutation with two parameters and no output schema, the description covers all needed aspects: behavior, side effects, idempotency, required permissions, and relationship to sibling tools. It fully prepares the agent to invoke the tool correctly and understand the consequences.

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

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

Schema coverage is 100% and already includes the constraint that persona_id must equal playbook_id. The description restates this and explains the reason (persona is stored on the playbook row), but adds no new syntax or format details beyond the schema. It doesn't compensate with additional field-level semantics, 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 specifies the exact action: resetting the playbook's singleton persona to the default Assistant name and system prompt. It clearly distinguishes this from delete_playbook, update_persona, and create_persona by explaining it is an overwrite, not a hard delete. The verb 'reset' plus the resource 'playbook's singleton persona' is specific and unambiguous.

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

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

Provides explicit usage guidance: use this tool to reset to default, use update_persona to change fields without resetting, use create_persona to set a new identity, and use delete_playbook only when removing the entire playbook. This makes when-to-use versus alternatives crystal clear.

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

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

The description explicitly states destructive consequences: 'Permanently delete' and 'This cannot be undone'. It also discloses the full scope of deletion: persona, skills, memory, API keys, canvas, and secrets. It further adds permission and ownership requirements, which go beyond the annotations. The annotations (destructiveHint=true, idempotentHint=true) align with the description - no contradiction.

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 long and front-loaded with the most critical info (permanently delete). It efficiently packs warnings, permissions, and exclusions into additional sentences. The only minor adjustment would be that the description could be slightly more concise, but it earns its space with high-value content.

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

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

For a destructive mutation tool with a single parameter, the description is complete. It covers consequences, scope, permissions, ownership, and alternative usage. The annotations and schema handle the rest (idempotency, parameter UUID). No output schema needed for a delete operation.

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 a single parameter (playbook_id) described as 'UUID of the playbook to delete'. The description doesn't add parameter-specific details but that's okay since the schema fully covers it. No additional semantic value is needed beyond what the schema provides.

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: 'Permanently delete a playbook and all of its contents', specifying the exact resource (playbook) and its scope (all contents). It also distinguishes from siblings by explicitly naming alternatives: 'Do not use this to reset a persona (delete_persona) or remove a single skill or 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 provides explicit usage guidance including when to use (deleting a playbook), when NOT to use (resetting persona, removing single skill/memory), and even names the alternative tools like delete_persona. It also covers the permission requirement ('Requires playbooks:write or full permission') and ownership restriction ('only the owner may delete').

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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds meaningful context: deletion is permanent, it includes isolated canvas artifacts, and it requires canvas:write or full permission. This goes well beyond the annotations without contradicting them.

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 sentences, each earning its place: first states the action and outcome, second states irreversibility and permissions, third provides alternatives and parameter targeting. Front-loaded and tightly written 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 destructive, two-parameter tool with no output schema, the description fully covers what is deleted, what cannot be undone, permission requirements, alternatives, and how to identify the target. No important behavioral gaps remain.

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 value by clarifying that playbook_id should be passed as 'the UUID or GUID of the playbook this call should target,' reinforcing the relationship between playbook_id and the run being deleted.

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

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

Description opens with a specific verb+resource pairing: 'Permanently delete a workflow run and its isolated canvas artifacts.' It clearly distinguishes from sibling tools like update_run and delete_playbook by naming the exact scope of the deletion.

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 guides when NOT to use this tool: 'Use update_run with status=archived to keep artifacts, and delete_playbook only when the whole playbook should go.' It also states the required permission, providing complete usage 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?

Beyond the annotations (destructiveHint, readOnlyHint), the description adds critical context: 'Cannot be undone' and 'This does not revoke the credential at the upstream provider'. It also states the permission requirement, enriching the agent's understanding of 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?

Three densely informative sentences with no filler. The main action and consequences are front-loaded, and every sentence serves a purpose (action, side-effect, alternatives, parameter hint).

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 two required parameters and no output schema, the description covers purpose, irreversible consequences, permission, non-revocation, and parameter targeting. It is fully sufficient 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?

Schema coverage is 100% and the description only restates the playbook_id format already in the schema. It adds no new semantic value for parameters, 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 opens with 'Permanently delete a secret', a specific verb+resource that clearly states the action. It also distinguishes itself from rotate_secret and list_secrets, making its unique 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?

Explicitly names alternatives ('Use rotate_secret to replace the value without removing the name, and list_secrets to confirm the name first'), provides a permission prerequisite, and gives context on when this tool is appropriate. This is model usage 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?

The description emphasizes the irreversibility ('This cannot be undone except by recreating the skill') and warns about the destructive nature, aligning with the destructiveHint annotation. It also states permission requirements, making the behavior 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 but includes essential warnings and alternatives. It is slightly verbose due to the permission and alternative mentions, but these are necessary for safe usage, so it remains well-structured.

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 destructive nature, permission requirements, alternative tools, and parameter usage, making it contextually complete for a delete operation without needing an 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?

The schema already fully describes both parameters (skill_id and playbook_id) with clear definitions. The description only reiterates the playbook_id parameter without adding new semantic information, so it adds minimal value 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 action as 'Permanently delete a skill from this playbook' and distinguishes it from alternative operations like rollback_skill and update_skill.

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

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

It explicitly mentions the required permission ('Requires full or skills:write permission') and provides clear guidance on when to use this tool versus alternatives, such as using rollback_skill for restoration or update_skill for content changes.

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?

Annotations already mark this as read-only, idempotent, and non-destructive, and the description reinforces this with 'Read-only and free of side effects.' It adds substantial behavior beyond annotations: name matches rank above description matches, results include full input schemas, and returned tools are callable even when absent from tools/list unless pinned with ?toolset=. No contradiction with 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 a single dense paragraph starting with the core purpose and then adding only high-value operational details: scope, ranking, limits, return contents, the tools/list caveat, and the ideal usage moment. Every sentence earns its place with no filler.

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

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

Given the full schema coverage, output schema, and annotations, the description is operationally complete. It covers what the tool searches, how results are ranked, what is returned, when to use it, and a critical boundary condition about direct invocation of returned tools.

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 at 100% coverage, so the baseline is 3. The description adds extra meaning by explaining query matching behavior (names and descriptions, with name-match ranking), reaffirming limit bounds, and specifying playbook_id as the target playbook identifier.

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: 'Search this playbook's complete tool catalog by keyword,' and it clearly enumerates both built-in and connected-server federated tools. This distinguishes it from sibling tools like list_mcp_servers or call_connected_tool by framing it as a discovery/search utility.

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 trigger: 'Use this when the tool you need is not in your current list, before concluding a capability is missing.' It also explains what gets searched and the important tools/list boundary, though it does not explicitly name alternative tools or list when-not-to-use cases.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces read-only status and adds useful context about returning section IDs/headings/levels for navigation and patch_canvas_section, going beyond the structured annotations without contradicting them.

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 tight sentences deliver purpose, return value, read-only note, alternatives, and parameter hint without any wasted words. Information is front-loaded with the primary action first.

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 output schema present and annotations covering safety, the description effectively complements the structured data. It references sibling tools for related operations, covers parameter nuance, and provides sufficient context for a tool of this 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 covers 100% of parameter descriptions, including slug, run_id, and playbook_id. The description adds extra clarity by specifying playbook_id as 'the UUID or GUID of the playbook this call should target' and implies slug discovery via list_canvas, enriching the parameter understanding 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 begins with 'Get the table of contents for a canvas document,' clearly stating the action and resource. It further specifies the returned data (section IDs, headings, levels) and distinguishes itself from read_canvas (full markdown) and list_canvas (slugs), making sibling differentiation explicit.

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: 'Use read_canvas for full markdown and list_canvas to discover slugs.' This tells the agent when not to use this tool and directs to alternatives. It also mentions the purpose for navigation and patch_canvas_section, establishing clear use cases.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description still adds genuine behavioral context: the tier-specific return shape, that entries carrying metadata.recording return with resolved links, and that after/before bound memory_at exactly as search_memory does. It does not disclose pagination or size limits, keeping it shy of a 5.

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

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

Purpose and read-only status are front-loaded, then filtering semantics, then sibling routing. It is dense but every sentence carries unique information (tier behavior, episode convention, time bounds, alternatives). Slightly long as one unbroken paragraph, which costs a point.

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 9 parameters, an output schema already present, and rich annotations, the description supplies everything else an agent needs: how tiers differ, how to filter, how to target the playbook, and how it relates to sibling memory tools. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above-baseline credit by explaining the semantics the schema only names: the metadata.episode {location, task, outcome} convention behind location/task, and that after/before are exact memory_at bounds matching search_memory. playbook_id is also clarified as a UUID or GUID.

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

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

Starts with a specific verb and resource ('Get a context-optimized view of memories') and immediately specifies the per-tier treatment (full working, summaries for contextual, keys only for longterm). It explicitly names the siblings it is not (read_memory, search_memory, get_memory_tree), so an agent can distinguish it without opening other schemas.

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

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

Gives an explicit use case ('use this to pack a prompt') followed by a routing table to alternatives with their distinct conditions: read_memory for one key, search_memory to filter by text or tags, get_memory_tree for parent-child task graphs. This is exactly the when-to-use/when-not guidance the dimension asks for.

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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered; the description adds genuinely new context that history is 'excluded from normal search' and how to restore a prior version. It does not say whether the history list is ordered or how the version payload is shaped, which keeps it short of a 5.

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

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

Something like four tightly packed sentences, each carrying distinct load: scope, search exclusion, restore path, sibling contrast, and a required-param note. The core purpose is front-loaded and nothing is redundant 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?

With no output schema, the description compensates by naming the returned data ('original memory_at and saved contents'). Pagination is handled by the richly described schema, and annotations carry the safety profile, so an agent has everything needed to call it and interpret results.

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 limit, offset, search, key, and playbook_id are already documented in the schema. The description only restates playbook_id's UUID/GUID format, adding no semantics beyond what the schema provides, 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?

States a specific verb+resource ('Read previous versions of a memory') and explicitly delimits scope by key. It also names and contrasts two siblings (get_memory_context for current-by-tier, get_memory_tree for hierarchy), so an agent can distinguish it without opening other schemas.

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

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

Gives explicit routing versus the two nearest alternatives and even supplies a follow-on workflow ('To restore a version, write its contents and memory_at with write_memory and is_archived=false'). It tells the agent both when to use this tool and what to do next, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's 'Read-only' reinforces this. It adds context beyond annotations by describing the hierarchical structure and per-node status, and the optional parameters' effect on output (summaries vs full values). No contradictions found, and the description enhances the agent's understanding of behavior beyond what annotations provide.

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 the core purpose, and efficiently covers usage context and parameter hint in the second sentence. No redundant phrases or unnecessary details—every sentence earns its place.

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

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

Given the tool's moderate complexity (4 params, output schema present, annotations provided), the description is complete enough. It covers the purpose, usage, and key behavior (read-only, hierarchical). It doesn't detail output format, but the output schema exists and annotations cover safety. The mention of 'per-node status' and 'visualize task graphs' gives sufficient context for selection.

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 description doesn't need to add much. It does mention the playbook_id format (UUID/GUID) which slightly adds to the schema, but the other parameters (root_key, max_depth, include_values) are not elaborated beyond what schema already provides. It adds minimal semantic value, but the schema already does the heavy lifting, so a 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?

Description clearly states the tool retrieves a hierarchical tree of memories with parent-child relationships and per-node status. It distinguishes from siblings by explicitly naming alternative tools (search_memory, get_memory_context, read_memory) for different use cases, 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?

Provides explicit guidance on when to use this tool vs alternatives: 'Use this to visualize task graphs; use search_memory to filter flat lists, get_memory_context for a tiered prompt view, and read_memory for a single key's full value.' Also specifies the target via playbook_id as UUID or GUID, which is actionable.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat those. It adds value by specifying the required permission level and the scope of what is returned (singleton persona, skills, connected MCP servers, memory). No contradiction with 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 concise, front-loaded with the main purpose, and every sentence adds value: what it returns, uniqueness, read-only nature, permission requirement, and usage guidance. 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?

Given the tool's moderate complexity (returns multiple related entities), the description covers the key aspects: what is returned, how to get the ID, when to use an alternative, and permission requirements. No output schema exists, but the description sufficiently explains the return scope. Annotations cover safety, so completeness is high.

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% (playbook_id is described as 'UUID of the playbook'), so the description doesn't need to add much. It mentions using list_playbooks to discover IDs, which provides context for the parameter's value. 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 the tool retrieves a playbook with its associated persona, skills, MCP servers, and memory. It explicitly notes this is the only persona retrieval tool, distinguishing it from siblings like get_skill and list_playbooks.

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 guidance: use list_playbooks to discover IDs first, and use get_skill when needing one skill's full content. Also mentions required permissions (playbooks:read or full), which helps the agent decide when to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'this lookup does not modify the skill' is largely redundant. However the description adds genuine behavioral value by explaining how demonstrations are returned (resolved list, link per recording and per segment, in performance order).

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 purpose, then identifier semantics, return shape, and routing guidance in a logical order. Slightly long, and the return-shape sentence partially duplicates the output schema, but every sentence carries information.

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

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

Given an output schema exists, the description need not restate returns, yet it goes further by describing demonstration resolution and ordering. Routing, identifier format, and mutation behavior are all covered, so nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description nevertheless adds meaning beyond the schema: skill_id 'may be a UUID or the skill's kebab-case name' (the schema only says 'Skill ID or name') and clarifies playbook_id is the UUID/GUID target.

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 (Return) and resource (full definition of one skill), and enumerates the returned fields (name, description, content, priority, attachments). It explicitly distinguishes itself from list_skill_versions and get_playbook, so an agent can route correctly without opening schemas.

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 (use list_skills first to discover IDs) and when-not (do not use list_skill_versions for historical revisions, nor get_playbook for persona/summaries). Names alternatives with the condition that selects them.

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?

Beyond the readOnly and idempotent annotations, the description states 'Read-only', explains the effect of omitting run_id (lists all runs), and clarifies the absence of a get_run endpoint, providing transparent behavioral details.

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

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

The description is concise, well-structured, and covers all necessary points without redundancy or irrelevant details.

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?

Provides complete context including purpose, parameter usage, relationships to other tools, and behavioral notes, leaving no major gaps 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?

Adds meaningful guidance on parameters beyond the schema: explains that run_id can be omitted to list all runs and that playbook_id should be a UUID or GUID, enhancing usability.

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

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

Clearly states the tool lists canvas documents in a workflow, defines canvas documents, and distinguishes from read_canvas and get_canvas_toc, 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?

Explicitly guides when to use this tool versus alternatives (read_canvas for content, get_canvas_toc for section IDs) and clarifies that list_runs is used for runs, not get_run.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description goes beyond by specifying the content returned (transport metadata, discovered capability counts) and clarifying it is the detail view. This adds meaningful 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 three sentences, each serving a distinct purpose: stating the action, clarifying read-only nature and the absence of a getter, and providing usage guidance. No fluff or redundancy, effectively 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 the simple tool (1 param, no output schema), the description fully covers what the tool does, what it returns, and how to use it. It also anticipates potential confusion with sibling tools, making it complete for agent decision-making.

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 single parameter playbook_id is fully described in the schema ('UUID or GUID of the target playbook'), and the description only repeats that instruction without adding additional semantics. With 100% schema coverage, 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 lists MCP and OpenAPI servers connected to a playbook, including transport metadata and capability counts. It distinguishes from siblings by explicitly noting there is no get_mcp_server and by contrasting with call_connected_tool, making its purpose unique.

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 when to use this tool (for listing/detail view) and when not to use it (not for invoking a tool, for which call_connected_tool is the alternative). It also instructs how to pass the playbook_id, providing clear 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?

Annotations already declare readOnly, openWorld, idempotent, and destructive properties, and the description reinforces these by stating 'Read-only; it does not create or modify playbooks.' The description adds the permission requirement and mentions the type of data returned (access role, content counts), but these are not major behavioral traits beyond what annotations provide, so a high but not maximal score is appropriate.

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

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

The description consists of three concise sentences, each conveying necessary information without redundancy. It is well-structured and 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?

The description provides sufficient context: it specifies the scope (owned or shared), what is included (access role, content counts), that it is read-only, offers an alternative for a single playbook, and mentions required permissions. Since an output schema exists, no need to describe return format separately.

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 no parameters in the schema, so there is nothing to explain. The description does not add parameter details, which is acceptable given the empty schema. According to the rubric, with 100% schema coverage, a 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 the tool lists playbooks owned or shared, including access role and content counts, and explicitly distinguishes it from get_playbook, which retrieves a single playbook with more detail. This makes the purpose specific and differentiates it from sibling tools.

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

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

The description explicitly advises using get_playbook for a single playbook with additional details, providing an alternative. It also mentions the required permission (playbooks:read or full), giving clear guidance on when and how to use the 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?

Annotations already declare readOnly and idempotent hints, and the description reinforces this with 'Read-only.' It adds helpful context about runs isolating canvas artifacts and execution context, and clarifies the absence of get_run, going slightly beyond the structured 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 front-loaded with the core purpose and remains focused. The final sentence about playbook_id is somewhat redundant with the schema, but the overall structure is efficient and each other sentence adds useful context.

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 a single required parameter, strong annotations, and no output schema, the description provides enough context to select and invoke the tool correctly. It explains what runs are, how they relate to canvases, and where to go for related operations.

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 playbook_id is already described as 'UUID or GUID of the target playbook.' The description mostly restates this, adding no new semantics beyond confirming the parameter's role.

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

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

The description clearly states the action: 'List workflow runs for this playbook.' It distinguishes this from related tools by explicitly noting there is no get_run and pointing to create_run and list_canvas as different operations.

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

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

Provides explicit guidance: use create_run to start isolated canvas context and list_canvas to see documents in a run. It also clarifies that there is no dedicated single-run getter, so list_runs is the way to retrieve run records.

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?

Discloses that secret values are never returned and specifies required permissions (secrets:read or full), adding behavioral context beyond the readOnly annotation.

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?

Concise, front-loaded summary followed by key behavioral notes and parameter instruction; no redundant wording.

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?

Covers what is listed (names and metadata), what is not returned (values), required permissions, and parameter usage, making it complete for a list operation.

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 both parameters; the description only clarifies playbook_id as 'UUID or GUID', but adds no new meaning for category, making it minimally additive.

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

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

Clearly states it lists secret names and metadata in a playbook, distinguishing it from sibling list operations like list_playbooks or list_runs via the resource type 'secrets'.

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 guidance on when not to use this tool (expecting plaintext) and directs to alternatives (use_secret, store_secret, rotate_secret) for other operations.

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?

States read-only nature and that it does not create or change skills. Reinforces annotations but adds explicit non-mutating wording beyond the hints.

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?

Each sentence adds value: purpose, read-only, usage, exclusions, parameter. No redundancy or fluff; well-structured and scannable.

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

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

Covers purpose, usage, return fields, and exclusions. Sufficient for an agent to decide when to call and what to expect, though error handling is not discussed (not required).

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

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

Schema fully describes the single parameter (playbook_id) with type and description. The description repeats the same info without adding new semantics, 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?

Clearly states the action (list), resource (skills), scope (playbook), and return fields (id, name, etc.). Explicitly distinguishes from sibling tools like list_skill_versions and get_playbook.

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 (discover skill_id before get/update/delete) and when-not-to-use (list_skill_versions for revisions, get_playbook for summary).

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 reinforces the safety profile with 'Read-only' and adds meaningful context that the tool exposes historical versions for auditing and rollback. It does not add detail about pagination or response shape, but the annotations already cover read-only, idempotent, and non-destructive behavior, so the bar is lower here.

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. The guidance sentence is slightly long but packs useful sibling differentiation into one line. Minor redundancy exists between 'rollback' in the first sentence and 'before rollback_skill,' but overall it is 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?

For a simple read-only listing tool with strong annotations and full schema coverage, the description gives enough context to invoke it correctly: what it lists, when to use it, where to use it, and the sibling relationship. The only minor gap is not describing what fields or structure the returned historical versions contain, but no output schema exists to fill that role.

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 input schema fully documents playbook_id, skill_id, and limit. The description does not add meaningful parameter meaning beyond noting that playbook_id is the target playbook, which the schema already states.

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 and resource: 'List historical versions of a skill.' It explicitly frames the tool for auditing and rollback purposes and distinguishes it from siblings by naming get_skill and list_skills as alternatives for current and all skills, respectively.

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 when-to-use guidance: 'Use this before rollback_skill.' It also clarifies when the sibling tools should be used instead—get_skill for the current definition and list_skills for all skills in the playbook.

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?

Annotations already indicate non-read-only, non-destructive, and idempotent. The description adds that it requires canvas:write or full permission, and that it should be paired with unlock. It doesn't mention what happens if already locked, but annotations cover the safety profile.

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 sentences, all essential. Front-loaded with the core purpose, then usage guidance, then parameter clarification. 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?

For a locking tool with good annotations and full schema coverage, the description is complete. It covers permissions, pairing with unlock, and parameter format. Could mention what happens if the section is already locked, but that's a minor gap.

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

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

Schema coverage is 100%, so all parameters are documented. The description adds context for playbook_id (UUID or GUID) and implies the locking mechanism, but doesn't add much beyond 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 the tool locks a section for exclusive editing, preventing other agents from modifying it. It distinguishes from siblings like patch_canvas_section (editing) and unlock_canvas_section (unlocking).

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 (for exclusive editing), when not to use (not for editing content), and pairs with patch_canvas_section. Also instructs to always unlock when finished, and specifies the playbook_id parameter format.

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?

Beyond the annotations (readOnly, idempotent, destructive flags), the description reveals additional behavioral traits: it is parallel-safe (only the targeted section is updated), requires canvas:write or canvas:admin permission, and explicitly mentions that playbook_id is a UUID/GUID. This provides a clear picture of the operation's side effects and safety.

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, well-structured paragraph that conveys all essential information without redundancy. It covers the purpose, usage, permissions, and parameter relationships, making it efficient and easy to read.

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 addresses the tool's purpose, concurrency safety, permissions, related tools, and key parameter acquisition (section_id). Given that there is no output schema, it covers the necessary context for an agent to correctly invoke the tool, including potential pitfalls like needing to lock the section.

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 descriptions for all parameters (100% coverage). The description adds value by explicitly stating that section_id should be obtained from get_canvas_toc and that playbook_id is the target playbook's UUID/GUID. This contextual guidance enhances understanding of these 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 tool edits a specific section of a canvas document, using the verb 'edit' and specifying the resource. It also distinguishes itself from write_canvas, which replaces the whole document.

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 guidance on when to use this tool versus alternatives: use write_canvas only for full replacement, and get_canvas_toc to obtain section_id. It also advises locking the section in multi-agent scenarios, which clarifies the intended usage 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?

Annotations give a low bar (non-read-only, non-destructive, non-idempotent), and the description adds real context beyond them: the explicit non-demotion constraint, the cumulative effect of repeated priority_boost calls, and the required permission (memory:write or full). It doesn't describe the response or failure modes, so not a 5.

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

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

Four sentences, each earning its place: purpose, boundary/alternative, repeat behavior, and permission. Front-loaded with the core action and 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 four-parameter mutation tool with full schema coverage and annotations, the description covers the important extras: permission requirement, non-demotion boundary, sibling routing, and repeat semantics. Missing only return-value/error behavior, which is minor given no 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%, so the schema already documents all four parameters including the enum and the 0-50 range. The description reiterates playbook_id format and notes priority_boost can be repeated, but adds little parameter syntax or semantics beyond the 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 uses specific verbs (restore visibility, promote tier, boost priority) applied to a named resource (a memory). It explicitly distinguishes itself from archive_memories and clarifies it cannot demote, so an agent can separate it from siblings despite the crowded toolset.

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 states when-not (cannot demote) and points to the alternative (use archive_memories to archive). It also explains the repeat-call behavior for priority_boost. It stops short of saying when to prefer this tool over, e.g., write_memory or read_memory, so a 4 rather than 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond the annotations: what the tool returns (full content, section structure, metadata) and the optional section-scoped read mode. It does not cover failure behavior or restrictions, but annotations cover the safety profile well.

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

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

The description is three sentences, front-loaded with the core purpose, and contains no filler. Every sentence contributes either the return shape, the optional section mode, or parameter sourcing guidance.

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 no output schema, the description covers the return values sufficiently (full content, sections, metadata). It also explains how to obtain section IDs and slugs, which is important in a tool ecosystem with many siblings. It does not clarify run_id's role, but the schema fully describes that parameter.

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 meaningful guidance: using get_canvas_toc to discover section IDs, using list_canvas to find slugs, and passing playbook_id as UUID/GUID. These references enrich the schema descriptions and help agents source correct parameter values.

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 a canvas document, returns full content, section structure, and metadata, and supports optional section-level reads. This distinguishes it from siblings like get_canvas_toc and list_canvas, which are explicitly positioned as discovery helpers.

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—read a canvas when you need full content or a specific section—and gives guidance for using get_canvas_toc to find section IDs and list_canvas to find slugs. However, it does not explicitly state when to prefer read_canvas over these sibling tools or when not to use it.

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

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

Annotations mark readOnlyHint=false, idempotentHint=false, destructiveHint=false — the description adds critical context that annotates why: reads increment access_count and update last_accessed_at as a side effect without changing stored value. This is exactly the value-add beyond annotations that earns a top 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?

Front-loaded with the read purpose, then behavioral caveat, then alternatives, then parameter guidance. Dense and every sentence carries information, though the multi-clause structure is slightly long for a 2-parameter tool.

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?

Complete for the tool's complexity: annotated side-effect behavior is explained, output schema exists (value/tags/tier/summary/metadata are named), sibling routing is exhaustive, and parameter constraints are clarified. Nothing an agent needs is missing.

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

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

Schema coverage is 100% for both key and playbook_id. The description reinforces playbook_id format ('UUID or GUID') and adds exclusions (do not pass memory_type), but with full schema coverage the baseline is 3 even with no param info in description.

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 ('Read one memory entry by key and return its value, tags, tier, summary, and metadata') and explicitly differentiates from siblings search_memory, get_memory_context, get_memory_tree, and write_memory. An agent can pick it apart from siblings without opening schemas.

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

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

Explicitly routes: 'not a pure read' side effect disclosed, 'no update_memory; use write_memory to overwrite', 'Use search_memory to find keys', and 'Do not pass memory_type; that filter belongs to search_memory'. When-to-use and when-not-to-use are both stated 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?

Adds important behavioral context beyond annotations: the replacement is irreversible except by rolling forward, and permission requirements are detailed. This complements the destructiveHint and idempotentHint annotations without contradiction.

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, with no unnecessary fluff. It packs purpose, usage, warning, and permission into a few clear sentences, well-structured for quick comprehension.

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 role among siblings, the description provides sufficient context: what it does, what it requires, and its limitations. It covers essential aspects without needing extra details.

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

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

Both parameters are well-described in the schema (version_id tied to list_skill_versions, playbook_id as UUID/GUID). The description reinforces the playbook_id usage, ensuring clear understanding.

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 purpose: rolling back a skill to a previous version. It also mentions that it replaces the current definition, which is specific and distinguishes it from other operations.

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

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

Explicitly states when to use (to revert to a previous version) and when not to (do not use delete_skill for reverting). Also specifies required permissions (full or skills:write) and provides guidance on parameter usage.

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

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

Annotations cover destructive/idempotent/readOnly, and the description adds substantial context beyond them: the old value is permanently irrecoverable, the expiry is preserved by default, null removes it, and it requires secrets:write or full permission. This is exactly the kind of destruction-and-auth detail annotations alone cannot convey.

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 core action and destruction warning, and each sentence carries distinct information (expiry behavior, auth, sibling routing, id format). It is dense but slightly long, with the playbook_id formatting note tacked on at the end.

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, no-output-schema mutation tool, the description covers everything an agent needs: what is destroyed, the expiry tri-state, permission requirements, and how it relates to store_secret/delete_secret/use_secret. Nothing material is missing.

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

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

Schema coverage is 100% so the schema already defines all four parameters; the description goes beyond it by explaining the expires_at tri-state semantics (date sets, null removes, omit keeps) and clarifying playbook_id expects a UUID or GUID. Minor because the schema largely duplicates this.

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

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

States a specific verb and resource ('Rotate an existing secret with a new value') and explicitly contrasts the scope against siblings by naming store_secret (create new) and delete_secret (remove). An agent can distinguish this from the other secret tools without opening any schema.

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

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

Gives explicit when-to-use and when-not-to-use guidance: 'Use store_secret to create a name that does not exist yet, and delete_secret to remove the secret entirely.' It also explains the intended remediation flow (an expired secret refused by use_secret becomes usable again via expires_at: null).

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the default scope filter, the fact that archived scope surfaces previous versions, and that results carry memory_at and a history_id that is null for current entries. It stops short of describing result ordering or paging behavior, so it is not a 5.

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

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

Four dense sentences, zero filler, and the most decision-relevant facts (what is searched, default scope, scope variants) are front-loaded ahead of the sibling routing and the playbook_id note.

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 12-parameter, no-output-schema search tool, the description covers the discriminating behavior (scope semantics, result fields, alternative tools) well. It omits result ordering and how search matching is done (the schema says 'literal text'), which are minor gaps rather than blockers for correct invocation.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented, including the scope enum and playbook_id. The description's prose about scope and playbook_id restates rather than extends the schema; the extra return-field note (memory_at, history_id) is output information, not parameter semantics. Baseline 3 is correct.

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 the exact fields searched ('keys, JSON values, descriptions and summaries'), and its scope semantics ('archived searches archived entries and previous versions') clearly separate it from siblings like get_memory_history and read_memory. An agent can distinguish it from the other memory tools without opening a schema.

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

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

It states the default behavior ('Defaults to current, non-archived memories'), defines what each scope value does, and routes the agent to explicit alternatives with the condition that selects them: get_memory_history for one key's prior versions, read_memory for its current value. That is the full when/when-not/alternatives triad.

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 goes beyond the annotations by disclosing the encryption algorithm (AES-256-GCM), that the value is never stored or returned in plaintext, and the permission requirement. It does not detail duplicate-name behavior or return values, but the annotations and schema already set a clear safety profile.

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 front-loaded and every sentence adds distinct value: purpose, encryption behavior, permissions, sibling tool guidance, and parameter targeting. There is no redundant or filler content.

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

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

For a create-style tool with no output schema and generic annotations, the description is thorough enough for correct selection and invocation. It covers security, permissions, alternatives, and the required targeting parameter, leaving no critical operational gap.

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

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

The input schema covers all six parameters with descriptions, so the baseline is 3. The description adds the explicit instruction to pass playbook_id as the target UUID/GUID, but this largely repeats the schema's existing parameter description and does not materially enrich parameter semantics.

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

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

The description states a specific action ('Store a new encrypted secret') with the resource and key security property. It distinguishes itself from sibling tools by explicitly referencing rotate_secret, list_secrets, and use_secret for adjacent operations.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: use rotate_secret for replacing an existing value, list_secrets to confirm names, and use_secret for authenticated requests. It also states the required permission level (secrets:write or full permission).

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?

Annotations already provide idempotent, destructive, and read-only hints. The description adds valuable transparency by stating it 'does not change section content' and clarifying permission needs, offering a clear behavioral contract beyond the 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 concise, consisting of three tightly written sentences without redundancy. It efficiently conveys purpose, usage, and a key distinction, maintaining excellent structure and focus.

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

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

For a simple tool with a clear schema and annotations, the description covers the essential context: action, effect, permission, and relationship to lock. It does not detail error conditions or return values, but those are not expected here, so it remains largely complete.

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

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

The input schema describes all four parameters (slug, run_id, section_id, playbook_id) with concise explanations. The description adds minimal extra detail (e.g., reiterating the playbook_id type), so the schema bears most of the semantic weight, yielding a baseline score.

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

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

The description clearly states the tool's function: 'Unlock a previously locked canvas section so other agents can edit it.' It also differentiates from siblings by noting it does not change section content and referencing lock_canvas_section, making its 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 provides explicit usage context: it explains when to use (to unlock a locked section) and mentions permission requirements ('Requires canvas:write or full permission'). It also directs users to lock_canvas_section for locking, effectively contrasting with 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?

Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description goes beyond these by clarifying that this updates 'stored' server configuration and requires a specific permission scope. It does not detail partial-update or overwrite behavior, but the annotation coverage plus the 'stored' framing make the tool's core behavior clear.

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

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

The description is four short sentences, front-loaded with the core purpose, then permission, alternatives, and target playbook context. Every sentence earns its place and supports either invocation or selection.

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

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

For a tool with 8 parameters, no output schema, and appropriate annotations, the description provides sufficient selection criteria, permissions, and payload scope. It does not cover update semantics such as whether partial fields replace or merge, or how nested arrays should be formatted, but these are partially inferable from the schema and do not prevent correct high-level 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 covers all 8 parameters with 100% description coverage, so the baseline is 3. The main description does not add much parameter-level detail beyond mapping broad categories like 'name, description, tools, resources, or transport' to the schema, and noting that playbook_id should be the target playbook. This is accurate but redundant with 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 specific action and resource: 'Update a connected MCP or OpenAPI server's stored name, description, tools, resources, or transport.' It clearly identifies which mutable fields are involved and distinguishes the tool from related server actions by naming call_connected_tool and delete_mcp_server.

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 when-to-use guidance: updating server metadata versus invoking tools via call_connected_tool versus disconnecting via delete_mcp_server. It also states a clear permission precondition: 'Requires playbooks:write or full permission,' and tells the agent to pass a playbook_id.

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?

Annotations already declare idempotentHint=true and destructiveHint=false, which the description aligns with by noting 'without resetting to defaults'. The description adds permission requirements (personas:write or full permission) and the singleton storage constraint, but does not elaborate on the exact update behavior (e.g., partial vs atomic updates) beyond what is implied. No contradictions, and with annotations present, the added context is useful 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, two sentences, and front-loaded with the primary purpose. The second sentence packs essential guidance about alternatives. No wasted words, though it packs many ideas into a single sentence which could be slightly clearer, but overall 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?

Given the tool's simplicity (no output schema, moderate parameter count), the description covers the essential aspects: purpose, key constraint, permissions, and alternatives. It lacks a note about possible validation errors or partial update semantics, but for this complexity level, it is fairly complete. The presence of nested objects (metadata) is not discussed, but the schema already covers that.

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 parameters are well documented in the schema. The description reinforces the persona_id=playbook_id constraint and the scope of updatable fields (name, system_prompt, metadata). It adds the alternative tool usage for replacing name and system_prompt together, which helps agents understand the parameter interplay, going slightly 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 updates a singleton persona's name, system prompt, or metadata without resetting defaults. It includes the critical constraint that persona_id must equal playbook_id, and distinguishes it from related tools like create_persona, delete_persona, and update_playbook, 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 explicitly provides when to use the tool (update persona fields) and when not to, recommending create_persona when replacing both name and system prompt, delete_persona for resetting to default, and update_playbook when also changing playbook-level fields. This gives clear decision guidance relative to 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?

The description clearly discloses the destructive/overwrite behavior: 'Replacement fields overwrite previous values.' It adds permission requirements and the persona overlap warning, which go beyond what annotations already signal. There is no contradiction with the provided readOnlyHint=false and destructiveHint=true 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 efficiently front-loaded with the core purpose, followed by warnings, permissions, alternatives, and ID format. Every sentence earns its place despite the tool having 10 parameters and a destructive nature.

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, destructive update tool with no output schema, this description is exceptionally complete. It covers purpose, overlap with siblings, permission requirements, overwrite semantics, and target ID format. The agent has all necessary context to select and safely invoke the 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 has 100% parameter coverage, giving the baseline of 3. The description adds valuable semantics beyond the schema by explaining that fields are replacements, specifying playbook_id must be UUID or GUID, and clarifying the distinction between instructions and persona fields. This meaningfully helps an agent pass parameters correctly.

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 precise verb and resource ('Update this playbook's name, description, visibility, tags, config, singleton persona fields, or always-on project instructions'), which makes the tool's scope immediately clear. It also differentiates this from sibling tools by explicitly noting overlap with update_persona and create_persona.

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 guidance on when NOT to use this tool: 'use those when only the persona should change.' It also clarifies how to read persona data via get_playbook, which prevents misuse. The permission requirement ('Requires full or playbooks:write permission') and caution ('Handle with extreme care') add practical usage 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?

Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds useful context: permission requirement, the fact that there is no get_run, and that delete_run removes the run and canvas artifacts. It does not contradict annotations, and adds value by warning about the missing get_run and articulating the permission boundary.

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?

Four sentences, each carrying necessary information: purpose, permission, lookup guidance, and playbook_id format. No fluff, well front-loaded with the main action. Ideal conciseness for a tool with 5 parameters.

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

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

Covers permissions, lookup workflow, and distinguishes from delete. The schema handles parameter details (enum, objects), and the description provides the operational context. It doesn't explain return values, but no output schema exists, so that's acceptable. Given the tool's complexity, this 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?

With 100% schema coverage, the baseline is 3, but the description adds extra hints: how to obtain run_id via list_runs, and that playbook_id should be UUID or GUID. This goes beyond the schema's basic descriptions and aids correct parameter usage.

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

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

Clearly states it updates a run's name, status, or context, with a specific verb and resource. It distinguishes from siblings by mentioning list_runs and delete_run as related, but also identifies what this tool does not do (no get_run).

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 prerequisites (canvas:write or full permission) and workflow context (use list_runs to find run_id, delete_run for removal). It does not explicitly say 'use this instead of X', but it gives clear context for when and how to use, and mentions alternatives for related actions.

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

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

Beyond the annotations (which only say readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses auth requirements and a branching behavioral mode: with skills:write the skill is modified, with skills:propose the change is stored as a pending_review proposal and the skill stays unchanged until approved. That is exactly the kind of consequence an agent cannot infer from 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?

Front-loaded with the core action and efficiently packs permissions, alternatives, and exclusions. The final sentence restating that playbook_id is a UUID/GUID duplicates the schema and is the one non-earning line.

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

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

For a mutation tool with no output schema, it covers the safety-relevant behavior (permission modes, proposal workflow, sibling routing). It stops short of stating what happens to fields omitted from the call or how validation failures on the content/frontmatter block are surfaced, but the essential invocation picture is present.

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 schema already documents all six parameters. The description's line about playbook_id being a UUID/GUID largely repeats the schema text and adds no new syntax or format guidance, 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 opening sentence names a specific verb (update) and resource (an existing skill in this playbook), and the following sentences explicitly separate this tool from create_skill, delete_skill, and rollback_skill. An agent can distinguish what this does and does not do without opening any schema.

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

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

Explicit routing: use create_skill to add, list_skill_versions before a risky edit, rollback_skill to restore, and a hard exclusion ('Do not use this to delete a skill'). It also states the permission-dependent mode of operation, so the caller knows the preconditions before invoking.

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?

Even with the `idempotentHint` annotation (which is true), the description adds valuable behavioral context: it explains the side effect on parent nodes ('the parent is auto-updated') and what the tool returns ('Returns the current subtree state'). It also mentions the required permission ('Requires memory:write or full permission'), which is beyond what the annotations provide. The `idempotentHint` is consistent with the update semantics.

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?

Four sentences, each carrying weight. The first sentence states the primary purpose, the second covers side effects, the third mentions permissions, and the fourth and fifth give usage direction and parameter format. Only minor redundancy (the UUID/GUID note could arguably be in the schema), but overall tight and well-structured.

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 moderate complexity (5 params, no output schema, annotations present), the description covers the essential side effects and permission requirements. It doesn't explicitly state what the return value looks like beyond 'the current subtree state', but the description's mention of that return is sufficient for an agent to understand the nature of the operation. It could mention error cases, but that's likely beyond scope.

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% description coverage for all 5 parameters, so the baseline is 3. The description doesn't add extra parameter-level semantics beyond what's already in the schema, but it does provide general context about `playbook_id` format and the tool's purpose. Since the schema handles the parameter documentation well, this is adequate.

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 purpose: 'Update the status of a task node in a hierarchical plan.' It uses a specific verb ('update') and resource ('task status in a hierarchical plan'), and adds crucial context about auto-updating parents. This effectively distinguishes it from similar update tools like `update_playbook` or `update_run`.

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 create_task_graph to build the plan, not this tool'), which directly addresses the sibling tool `create_task_graph`. It also instructs on the required parameter format ('Pass playbook_id as the UUID or GUID'), making it exceptionally clear when and how to use it. The note about the alternative tool is a model example of usage 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?

Beyond the annotations, it discloses that the secret is never returned to the agent, is decrypted and used server-side only, and that only safe methods are accepted. It also notes permission requirements and that the caller chooses the URL, which adds meaningful behavioral context not inferable from the annotations alone.

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 front-loaded with the core action, then adds permissions, an example, sibling alternatives, and the playbook_id note. It is information-dense with no filler; every sentence contributes to correct selection and invocation.

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

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

For a tool with 8 parameters, nested objects, no output schema, and remote-API variability, the description is sufficiently complete. It covers the main mechanics, security behavior, permissions, example usage, and sibling differentiation; the remaining parameter details are already handled by the input 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 already 100%, so the baseline is 3; the description adds value by explaining how secret injection works, showing an example with Authorization: Bearer <key>, and clarifying that method is limited to safe GET/HEAD. This goes beyond the schema without needing to repeat all parameter 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 tool sends GET or HEAD requests with a secret injected as a header and returns the response. It also distinguishes the tool from its sibling use_secret_write by explicitly limiting methods to GET/HEAD.

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 guidance: use list_secrets to discover names, use_secret_write for POST/PUT/PATCH/DELETE, and store_secret or rotate_secret to change values. It also states the required permission (secrets:read or full permission), making invocation context clear.

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

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

The description discloses that the secret is never returned to the agent, is decrypted server-side, changes state, and cannot be undone. While annotations already indicate destructiveHint=true and readOnlyHint=false, the description adds crucial security context (secret not leaked) and irreversibility.

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 with a clear first sentence, followed by behavioral warnings and usage alternatives. It is slightly long but every sentence adds value, and it front-loads the core purpose.

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

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

Given 9 parameters, 100% schema coverage, and no output schema, the description sufficiently covers the tool's behavior and safety. It doesn't explain return format but that's not required without an output schema. The complexity is high, but the description handles it well.

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 a few nuances (header injection, prefix defaults, method default) but mostly repeats schema info. It doesn't explain the semantics of extra_headers or body beyond what's in the schema.

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

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

The description clearly states the tool sends POST, PUT, PATCH, or DELETE requests with a secret injected as a header, distinguishing it from use_secret (GET/HEAD). It also clarifies the purpose is to perform state-changing operations on remote APIs.

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 (state changes) and when-not-to-use (use use_secret for GET/HEAD, list_secrets for discovery, store_secret/rotate_secret for changes). Also notes the caller chooses the URL and should refer to the target API's documentation.

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?

Annotations already declare destructiveHint=true, and the description reinforces this by stating 'A replace overwrites prior content and cannot be undone.' It adds unique context about auto-parsing markdown headings into sections and the permission requirement, which goes beyond the 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 concise (two sentences) and front-loaded with the core purpose, followed by key usage notes and alternatives. Every clause provides value 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 write operation with full schema coverage, the description covers purpose, usage context, destructive behavior, and prerequisites. The lack of an output schema is fine, and the description sufficiently explains the tool's role in the canvas workflow.

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