AgentPlaybooks

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

Discloses that entries are kept (not deleted), filters combine as AND, and permission requirements. Annotations already indicate idempotent and non-destructive, but the description adds semantics about filter combination and permission. 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 front-loaded with the main purpose. Each sentence adds distinct value: purpose, non-destructive nature, filter logic, permissions, and alternatives. No fluff. Effectively structured in four sentences covering all key aspects.

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, no output schema, and moderate complexity, the description covers usage scenario, permission, filter behavior, alternatives, and parameter guidance. It is complete enough for an AI agent to invoke correctly without additional context.

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

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

Schema coverage is 100%, but description adds value beyond schema by explaining that filters (keys, tags, from_tier, older_than_hours) combine as AND, and explicitly states playbook_id must be a UUID or GUID. This clarifies parameter usage beyond the schema's basic 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 purpose: archiving memories from working or contextual tier to longterm. It distinguishes from siblings by explicitly mentioning alternatives (delete_memory, promote_memory, consolidate_memories). The verb 'archive' plus the resource 'memories' 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?

Explicitly states when to use this tool vs alternatives: 'Use delete_memory for irreversible removal, promote_memory to move a key the other way, and consolidate_memories when you also want a parent summary.' Also mentions the permission requirement (memory:write or full). This provides clear decision 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 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 signal non-read-only, non-idempotent, non-destructive behavior. The description adds useful behavioral context by stating the permission requirement and warning to check for name collisions before creating, which goes 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?

Three front-loaded sentences convey purpose, permissions, alternative tools, and the key target parameter without filler. Every sentence contributes actionable 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?

The description covers purpose, usage context, permissions, collision checking, and the target parameter. It does not describe post-creation behavior or error semantics, but for a straightforward create tool with full schema coverage, the provided context is sufficient 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 the input schema already documents all five parameters. The description mainly restates playbook_id's format/role and does not add significant new parameter-level meaning 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 states exactly that it creates a new skill for a playbook, using the specific verb 'Create' and naming the resource ('skill'). It also distinguishes itself from update_skill, list_skills, and other sibling tools by explicitly framing the action as expanding capabilities.

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: use update_skill to change an existing skill, use list_skills to check for name collisions, and it lists required permissions. This clearly tells the agent when to use this tool versus 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description clarifies the permanence: "cannot be recovered" and "The row is removed from storage, not moved to another tier." It also discloses permission requirements and the distinction from archival, adding meaningful context not present in 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 follows with permission, alternatives, an exclusion guardrail, and a parameter clarification. Every sentence adds distinct value with no filler or tautology, making it efficient for its length.

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

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

For a destructive tool with no output schema, the description provides all necessary context: irreversibility, permission, scoping via playbook_id and key, and clear alternatives when deletion is not the desired action. An agent can safely and correctly decide to invoke this tool.

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

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

The input schema already covers both parameters with descriptions (Memory key to delete, UUID or GUID of the target playbook), and schema coverage is 100%. The description's mention of passing playbook_id as UUID/GUID is redundant with the schema, and the key is only described as "by key," matching the schema without adding new 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 opens with a specific verb and resource: "Permanently delete one memory entry by key from this playbook." It clearly defines scope (one entry, by key, in this playbook) and highlights irreversibility, distinguishing it from archive_memories and consolidate_memories in the sibling list.

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 archive_memories to keep the entry in the longterm tier, or consolidate_memories to retain child detail under a parent summary." It also states "Do not call this when you only want to hide completed work," and specifies the credential requirement (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 and idempotentHint, and the description aligns with these by implying a read-only operation. It adds context about the tier structure but does not detail any side effects (none expected). Slight extra value beyond annotations, so a 4 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?

Two concise sentences with no redundant fluff. The description efficiently conveys purpose and usage without unnecessary 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?

Given the presence of an output schema (not shown but indicated) and full parameter coverage, the description is complete. It answers what the tool does and when to use it, and the output schema handles return 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?

Schema descriptions are complete, and the description enhances them by explaining the tier semantics (full working memory, summaries for contextual, keys only for longterm). This adds meaningful context not present in the raw schema, fully clarifying 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 retrieves a context-optimized view of memories, distinguishing tiers (working, contextual, longterm) and differentiating from sibling tools like read_memory, search_memory, and get_memory_tree.

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 explains when to use this tool ('pack a prompt') and contrasts with alternatives (read_memory for one key, search_memory for filtering, get_memory_tree for parent-child graphs), providing clear 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?

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?

Description states 'This lookup does not modify the skill,' consistent with annotations readOnlyHint true, idempotentHint true, destructiveHint false. It adds context beyond annotations by detailing identifier flexibility (UUID or kebab-case name) and return contents, which is useful for agent decision-making.

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?

Description is compact (4 sentences) and front-loaded with the core purpose. Every sentence adds distinct value: what it returns, how to identify, safety, usage order, alternatives, and how to pass playbook_id. No redundancy or filler.

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

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

For a simple lookup with only two parameters and a rich output schema, the description covers purpose, identification method, non-mutating behavior, discovery workflow, and exclusions. It is fully complete for this tool's complexity, especially given strong annotations.

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

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

Schema coverage is 100%, providing baseline 3. Description adds value by explaining skill_id may be UUID or kebab-case name and advising 'Use list_skills first to discover IDs and names,' which helps agents construct parameter values correctly. This extra guidance pushes score beyond baseline.

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

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

Description clearly states 'Return the full definition of one skill in this playbook' and lists included fields (name, description, content, priority, attachments). It explicitly differentiates from siblings list_skill_versions and get_playbook, stating what they do NOT provide, so purpose is specific and distinct.

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_skills first to discover IDs and names' and 'Do not use list_skill_versions (historical revisions) or get_playbook (persona and summaries, not full skill content).' This clearly directs when to use this tool versus 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?

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 are minimal (all hints false). The description compensates by disclosing that repeated calls with priority_boost increase priority again (non-idempotent), and it states the limitation of no demotion. It does not elaborate on exact side effects on the memory's tier or other attributes, but the primary behavior is transparent. 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 three focused sentences: purpose, limitation/alternative, and permission/ID guidance. Every sentence adds substantive information without any fluff. It is front-loaded with the core action and wastes no words.

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

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

Given the tool has 4 parameters, full schema coverage, no output schema, and minimal annotations, the description covers key context: purpose, constraints, permissions, and a reference to an alternative. It does not specify what 'higher tier' means in terms of the enumerated values, but the no-demotion rule implies the direction. Overall, it is adequately complete for a mutation 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 coverage is 100%, so baseline is 3. The description adds value by clarifying that playbook_id should be a UUID/GUID, and it explains priority_boost behavior (repeated calls increase priority again). This goes beyond the schema's simple attribute descriptions and ties the parameters to the tool's purpose.

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

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

The description clearly states the tool's function: promote a memory to a higher tier or boost priority. It distinguishes itself from archive_memories by explicitly noting it cannot demote and delegates that to archive_memories, which is a sibling.

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 (for promotion or priority boost), when-not-to-use (cannot demote), and names an alternative (archive_memories). It also includes permission requirements and a concrete instruction about playbook_id format, which fully guides invocation.

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?

The description goes beyond the annotations by explicitly stating this is not a pure read, describing the side effects (increments access_count, updates last_accessed_at) and clarifying that the stored value is unchanged. It also preemptively addresses the missing update_memory tool. The annotations (readOnlyHint: false) are consistent with this, so 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, each earning its place. It front-loads the core purpose, then the side-effect caveat, then practical usage guidance. There is no fluff or redundancy.

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

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

The tool is relatively simple (2 parameters), and the description covers purpose, side effects, alternatives, and a parameter format caveat. The output schema is present, so the description does not need to detail return structures. This is complete for an agent to select and invoke correctly.

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

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

The input schema already covers both parameters with 100% coverage, so the baseline is 3. The description adds value by specifying that playbook_id should be a UUID or GUID and by warning against passing memory_type (which belongs to search_memory). This goes beyond the schema's own descriptions.

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

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

The description uses a specific verb ('read one memory entry by key') and explicitly lists the return fields (value, tags, tier, summary, metadata). It also distinguishes itself from sibling tools by explaining there is no update_memory and by naming alternative tools for different use cases.

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 guidance by naming alternatives: use search_memory to find keys, get_memory_context for tiered summaries, and get_memory_tree for hierarchical graphs. It also states what NOT to pass (memory_type) and clarifies the correct format for 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?

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?

The description goes beyond the annotations by explicitly warning that the old value is permanently replaced and cannot be recovered, and it states the permission requirement. This provides crucial behavioral context that the annotations do not fully convey, even though destructiveHint is true.

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 sentences that convey all necessary information without redundancy or fluff. It is well-structured and easy to parse.

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

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

The description fully covers the tool's purpose, side effects, required permissions, and related tools. It is complete for a destructive mutation operation, including irreversibility and parameter guidance, without needing to explain return values (since no output schema is specified).

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?

While the schema already describes each parameter, the description adds extra value by clarifying that playbook_id should be a UUID or GUID, which is not present in the schema. This enhances the agent's understanding of the expected input format.

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 ('Rotate an existing secret'), identifies the resource (secret), and distinguishes from siblings by explicitly contrasting with store_secret and delete_secret. It 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?

The description provides explicit guidance on when to use the tool (for rotating existing secrets) and when not to (use store_secret for creation, delete_secret for removal). It also mentions required permissions ('secrets:write or full:access'), enabling the agent to judge applicability.

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. The description adds behavioral context beyond annotations by stating 'Returns summaries for large memories' and confirming 'Read-only aside from returning matches; it does not write entries.' No contradiction; the description complements the annotation 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 three sentences that are front-loaded with the main action and purpose. Every sentence adds value: the first states the function, the second advises on filter semantics, and the third names alternatives and the required parameter. No fluff or redundancy.

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

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

For a tool with 7 parameters, high schema coverage, and no output schema, the description is exceptionally complete. It covers what the tool does, when to use it, how to differentiate filters, how it differs from siblings, the required parameter format, and a note on return behavior (summaries). All essential contextual information 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%, but the description enriches parameter meaning: it explains how tags, tier, and memory_type should be used (categorical, archiving, task graphs). It also clarifies playbook_id as 'UUID or GUID', which is not obvious from the schema. This goes beyond the bare schema definitions.

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: 'Search memories by text, tags, tier, or type' with actionable details. It explicitly distinguishes itself from siblings like read_memory, get_memory_context, and get_memory_tree, making it unambiguous which tool to select for memory search.

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

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

Provides explicit when-to-use guidance: 'Use tags for categorical search; use tier to focus on active vs archived data; use memory_type to find task graphs.' It also names alternative tools for specific use cases and specifies the playbook_id parameter format, giving clear direction on invocation.

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?

Annotations already provide idempotentHint and non-destructive status. The description adds behavioral context beyond annotations, including permission requirements, the risk of editing, and the explicit exclusion of deletion. This meaningfully enriches the annotation-only information.

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 concise, information-dense sentences. Purpose is front-loaded, followed by permission, related-tool guidance, a usage exclusion, and a note on playbook_id. No unnecessary words 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 no output schema and six parameters, the description covers purpose, permissions, variant selection, and a critical exclusion. It does not explicitly clarify partial-update semantics or what happens when name/content are omitted, but for a mutation tool with reasonable annotations and high schema coverage, it is sufficiently complete.

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

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

Schema coverage is 100%, so the schema itself fully documents all six parameters. The description mostly restates playbook_id guidance already present in the schema ('UUID or GUID') and adds no further parameter-level semantics 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 'Update an existing skill in this playbook,' specifying the action and target resource. It is further differentiated from siblings by naming create_skill, list_skill_versions, and rollback_skill as related but distinct 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 the tool versus alternatives: use create_skill to add, list_skill_versions before risky edits, rollback_skill to restore, and not for deletion. Also provides the required permission level (full or skills:write), giving clear contextual 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?

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.

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

Schema description coverage is 100%, so all parameters are already documented. The description adds minimal extra semantics, primarily noting that playbook_id is a UUID/GUID, which duplicates the schema. No additional parameter guidance is provided beyond what the schema already offers.

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: 'Create or fully replace a canvas document.' It uses specific verbs (create/replace) and a specific resource (canvas document), and distinguishes itself by explicitly mentioning patch_canvas_section for partial updates.

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 given: 'Use patch_canvas_section for partial updates and lock_canvas_section before multi-agent edits.' It also mentions permission requirements (requires canvas:write or full permission), which helps the agent decide when to call 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?

The description clearly discloses the consequential overwrite behavior: 'a second write to the same key replaces the previous value and cannot be undone.' It also adds permission requirements and confirms no update-only variant exists, going 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?

Every sentence delivers distinct, actionable information: core behavior, overwrite consequence, tier guidance, hierarchical usage, permission, and sibling alternatives. It is compact and well structured with no repetition of schema text.

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 12 parameters, the description provides core behavior, irreversibility, permission requirements, lifecycle usage, task-graph construction, target playbook identification, and alternatives. This is sufficient context for an agent to select and invoke the tool correctly even without 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?

Schema coverage is 100%, so the description does not need to repeat each field. It adds valuable semantic context for tier values and the hierarchical memory_type plus parent_key combination, and it explains the intended use of playbook_id. This exceeds the baseline, though optional parameters like tags/metadata remain only schema-defined.

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

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

The description starts with a specific verb+resource: 'Create or overwrite a memory entry by key.' It explicitly disambiguates from a separate update_memory and names alternative memory operations, making the tool's 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?

It gives concrete when-to-use guidance for tiers, hierarchical graph building, and permission requirements. It explicitly directs the agent toward delete_memory, archive_memories, and read_memory for different needs, which distinguishes it from siblings.

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