AgentPlaybooks

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent, open-world write, so the safety profile needs no restating. The description contributes the useful structural fact that a playbook bundles persona/skills/memory, but says nothing about duplicate-name behavior, whether persona_* fields are applied at creation time only, or what gets created by default.

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

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

A single front-loaded sentence with no filler. It is arguably under-specified rather than padded, but nothing in it is wasted.

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 an 8-parameter creation tool with nested persona metadata and no output schema, the description omits what the response looks like (e.g., an ID needed by later calls), defaults behavior, and whether skills/memory can be attached at creation or only afterward. The 'skills and memory' mention implies capability the schema does not expose, leaving a 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% and each of the 8 parameters carries a description, so the schema does the heavy lifting. The description only hints at the persona grouping that explains persona_name/persona_metadata/persona_system_prompt as a set; 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?

Specific verb+resource: 'Create a new playbook container' tells the agent exactly what is produced, and 'container for a singleton persona, skills, and memory' clarifies the object model, which distinguishing it from update_persona and get_playbook. It stops short of naming a sibling or exclusion, so it's clear but not fully differentiated.

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

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

There is no guidance on when to create a playbook versus when to update an existing one via update_persona, or what prerequisites (org/workspace, permissions) apply. The agent must infer usage entirely from the name and short phrase.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one behavioral nuance — that schemas are included by default and can be dropped for compact results — but says nothing about result ordering, truncation, or how matching works beyond 'keyword'.

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

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

A single compact sentence with the core action front-loaded and the secondary toggle after the semicolon. Nothing is wasted and there is no filler.

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

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

An output schema and full annotation set carry most of the load, so the description does not need to explain return values. However, for a discovery tool operating inside a playbook, it omits the scoping effect of playbook_id and any hint about how many/which tools are searchable, which are the main gaps.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including defaults and the limit cap. The description's 'include_schemas=false for short summaries' largely restates the schema rather than adding new meaning, so the baseline of 3 applies.

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

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

The description gives a specific verb (find) and resource (operations/tools) plus the matching mechanism (keyword). It is clear what the tool does, but the term 'operations' sits awkwardly against the tool name 'find_tools' and the description never differentiates it from siblings like list_mcp_servers or list_skills.

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 only guidance is a parameter-level hint about include_schemas=false. There is no statement of when to use this tool versus list_mcp_servers/list_skills, no mention of what happens without a query, and no prerequisite context such as how playbook_id scopes results.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that secrets are not read and data is not changed, which is useful context beyond the annotations, but it does not describe what diagnostic information is returned.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently states the action and the safety boundaries.

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

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

For a simple, no-parameter, read-only diagnostic tool with rich annotations, the description covers scope and safety well enough to invoke it correctly. It could be slightly more complete by indicating what connection details or diagnostics are returned, especially since there is no output schema.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain. Per the rubric, zero parameters establish a baseline of 4.

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 ("Inspect") and resource ("this authenticated connection"), and the title adds the diagnostic framing. It is clearly distinct from sibling read tools such as get_profile or list_mcp_servers, though it does not explicitly differentiate itself from them in the description.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor any when-not-to-use conditions. The diagnostic intent is only implied by the title, not stated in the description.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds useful return-shape context (singleton persona, compact skill, server and memory metadata), but does not explain pagination behavior of memory metadata or what happens when the playbook id is unknown.

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

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

A single front-loaded sentence with no filler; the resource and payload contents come first. It is dense but every phrase carries information.

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

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

With no output schema, the description does a fair job naming the returned components, but a four-parameter read tool with paging and a full-payload mode would benefit from a sentence on error cases or when to prefer include_content=false plus targeted reads.

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 four parameters are documented, including the compact-mode paging and the include_content restore flag. The description adds nothing parameter-specific beyond the word 'compact', so the baseline 3 applies.

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

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

States a specific verb and resource (get a playbook) and enumerates what comes back: persona, compact skill, connected-server and memory metadata. It does not distinguish itself from list_playbooks or get_skill, so an agent must infer the boundary from the name alone.

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

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

No guidance on when to call this versus list_playbooks (discovery) or get_skill (detailed skill retrieval). The description never mentions the include_content tradeoff or that memory_limit/offset only apply in compact mode, leaving routing to the agent's guesswork.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the description carries a lighter burden. It adds the useful detail that the profile comes from validated credentials, but does not address behavior on expired or invalid credentials, which is the main failure mode an agent would want to know about.

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

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

A single front-loaded sentence with no filler. Every word contributes to identifying the resource and its scope, and there is nothing an agent must read past.

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

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

An output schema exists, so return-value structure need not be explained, and there are no parameters to cover. The remaining gap is minor: the description does not say what happens when credentials are missing or invalid, but for a read-only zero-argument tool this is close to sufficient.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a no-parameter tool applies. Nothing in the description conflicts with the empty schema.

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

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

States a specific verb (return) and resource (the profile) scoped to the current connection's credentials. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling get_connection_info, which an agent might reasonably confuse with it.

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 phrase 'validated credentials' implies the prerequisite that a connection must already be authenticated, which hints at when the tool is usable. However, there is no explicit when-to-use guidance and no mention of when to prefer get_connection_info instead, leaving the choice between these two closely related siblings to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description usefully discloses the return shape (content + metadata + attachment manifest). It says nothing about failure behavior when a skill or playbook ID is unknown, or about cost of pulling large attachment bodies.

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

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

A single front-loaded sentence that names the resource first and then the three returned components. No filler, no restatement of the tool name.

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

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

With an output schema present and 100% parameter coverage, the description needn't document return values or defaults, and it correctly doesn't. What's missing is edge-case behavior (missing skill/playbook, cross-playbook ID handling), which is minor for a read-only getter.

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% and every parameter carries its own doc string, including the include_content/include_attachments defaults, so the baseline is 3. The description mentions the attachment manifest with filenames and sizes, adding a little meaning to include_attachments, but nothing about skill_id accepting a name versus an ID.

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

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

Specific verb and resource ('Return the full definition of one skill') plus an enumeration of the payload (SKILL.md content, metadata, attachment manifest). It does not distinguish itself from get_skill_reference or list_skills, so an agent must infer the boundary rather than being told.

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?

Fetching a single skill by ID/name implies its use case, but the description never states when to prefer it over list_skills (enumerate) or get_skill_reference (single attachment). No exclusions, prerequisites, or alternatives are given in the description text.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds real behavioral detail — single-file granularity and heading-plus-subsections scoping — but says nothing about truncation/failure behavior when a filename or section isn't found.

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

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

A single sentence that front-loads the verb, the resource and the hard 'exactly one' constraint, with the optional mode trailing. No filler.

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

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

An output schema exists and returns are not the description's job; with 100% param coverage the remaining burden is modest. What's missing is minor but real: no hint about how a large file is continued across calls (offset chaining) or what happens for an unknown section/filename.

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%, including offset semantics tied to 'the previous next_offset' and max_chars bounds, so the baseline is 3. The description adds one genuinely new fact — that a section read includes its subsections — but leaves the required trio (playbook_id, skill_id, filename) entirely to the schema.

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

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

States a specific verb and resource ('Read exactly one skill file') with an explicit scope constraint plus an optional section-scoped mode. It doesn't distinguish itself from the nearby get_skill / get_playbook siblings, so an agent must infer that this reads file contents rather than skill metadata.

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 'exactly one skill file' phrasing implies one-file-per-call usage and the section mode implies a targeted-read path, but no sibling is named as an alternative and there is no when-not-to-use guidance. Pagination guidance exists only inside the schema's offset description.

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, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond this — no pagination behavior, no volume expectations, no note on whether listing requires playbook access. It also implies run-scoping while run_id is optional per schema, a mild tension the description never resolves.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though the brevity comes at the cost of the missing differentiation and behavioral detail noted elsewhere.

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

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

An output schema exists, so return values needn't be explained, and both parameters are fully documented in the schema. Still, for a list tool sitting alongside read_canvas and write_canvas, the absence of any routing guidance leaves an agent to infer selection from the name alone.

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%, including the key semantic that omitting run_id lists across all runs, so the schema does the work and the baseline applies. The description itself adds no meaning about either parameter.

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

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

States a specific verb and resource ('List canvas documents') and scopes it to a workflow run, so the operation is unambiguous. It does not distinguish itself from sibling tools like read_canvas or write_canvas, which is the only thing keeping it from a 5.

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

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

There is no guidance on when to choose this over read_canvas, write_canvas, or get_playbook. The description gives no prerequisites, no exclusions, and no indication of what happens when playbook_id is supplied but run_id is not.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful context by noting that results include transport metadata and discovered capability counts, though it does not mention pagination or ordering.

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

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

A single front-loaded sentence states the operation, scope, and return contents without filler. Every phrase contributes useful information.

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

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

For a simple read-only tool with one fully documented parameter and complete safety annotations, the definition is nearly complete. It describes the returned content at a high level, though details such as result ordering or empty-list behavior are not covered.

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

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

The input schema has 100% description coverage and documents playbook_id as a UUID or GUID. The description reinforces that the listing is scoped to a playbook, but adds no parameter syntax or format 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 gives a specific verb and resource: it lists MCP and OpenAPI servers connected to a playbook. It also adds scope and return-content detail, making it clearly distinct from sibling tools such as list_playbooks or get_connection_info.

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

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

It implies the tool is used to inspect servers connected to a specific playbook, but it does not explicitly state when to use this instead of related tools like get_connection_info or find_tools. The usage context is clear enough but not fully guided.

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, idempotent, closed-world and non-destructive behavior, so the safety profile is covered. The description adds two things annotations cannot: the authorization scope (owned by or shared with the authenticated user) and the fact that matching is literal rather than fuzzy, which sets expectations about recall.

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

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

A single sentence with no filler; the access scope and matching mode are front-loaded where an agent will read them first. Nothing is wasted or buried.

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

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

An output schema exists so return values need no explanation, all three parameters are fully documented in the schema, and access scope is stated. The only residual gap is a hint about whether shared items are distinguishable in results, which is minor.

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

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

Schema coverage is 100% and each parameter already carries a precise description, including the 1-100 limit and the 1000-match page cap. The description's 'literal name fragment' reinforces the query parameter's semantics but adds nothing the schema does not already say, so the baseline of 3 applies.

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

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

States a specific verb ('Find'), a specific resource (playbooks), and the exact scope (owned by or shared with the authenticated user). The matching mode (literal name fragment) further pins down what the call returns, distinguishing it from get_playbook or create_playbook without naming them.

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 retrieval-by-fragment, and the schema's 'omit to browse' note fills in the no-query case, but the description itself never says when to prefer this over get_playbook or how it relates to sibling search tools. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the response is metadata-only, field description is capped at 512 characters, and full SKILL.md content is deliberately excluded by default to keep discovery small. It stops short of stating ordering or behavior for an unknown playbook_id.

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

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

One sentence, front-loaded with the verb and scope, with the field list attached rather than spread across separate sentences. No filler or restatement of the title.

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 read-only two-parameter list tool with full schema coverage and an output schema, this covers the important behavioral choice (metadata vs. full content). Minor gaps remain around result ordering, pagination, and error behavior for an invalid playbook_id, but nothing blocks a correct call.

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 both parameters are already documented, including include_content's default and rationale. The description reinforces the metadata-vs-content distinction and the 512-character cap, but adds no syntax or format detail for playbook_id. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List every skill currently attached to this playbook') and enumerates the metadata fields returned, so the agent knows exactly what comes back. It does not explicitly distinguish itself from the sibling get_skill or get_skill_reference, which is the only thing keeping it off a 5.

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

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

Usage is only implied: 'as metadata' and 'omitted by default to keep discovery small' suggest this is the lightweight discovery call before reaching for get_skill, but the description never names the alternative or says when to prefer it. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no note on what is returned, whether missing documents error out, or how the playbook/run/slug hierarchy resolves. With annotations carrying the burden, this still leaves the description thin.

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 single sentence is efficient and front-loaded, but it is under-specified rather than genuinely concise — there is simply very little content to waste.

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

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

This is a read tool with three required hierarchical identifiers and no output schema, so the description should clarify what the document content looks like and how sections are selected. It covers none of that, leaving the agent to guess the return shape and the purpose of section_id.

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 four parameters (slug, run_id, playbook_id, section_id) are documented in the schema itself. The description adds no extra meaning, which is acceptable given the high coverage baseline of 3.

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

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

"Read a canvas document" restates the tool name and title without adding a specific verb+scope combination. It does not distinguish the tool from siblings like list_canvas, write_canvas, or get_playbook, so an agent gets no signal about what makes this a read of a single canvas versus a listing.

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

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

There is no guidance on when to use this tool versus list_canvas or write_canvas, and no mention of prerequisites such as needing an existing run_id or slug. The agent must infer usage entirely from the name.

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 presents this as a pure read ('Read one memory entry... return its value'), but annotations declare readOnlyHint=false. That is a direct contradiction of the tool's stated side-effect profile, and the description adds nothing about permission needs, missing-key behavior, or side effects.

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

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

A single front-loaded sentence with no filler; the verb, scope, and return shape all land immediately.

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

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

An output schema exists, so spelling out return fields is redundant but harmless. What's missing is behavioral context: what happens when the key doesn't exist, and any reconciliation of the read semantics with the non-readOnly annotation.

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 both playbook_id and key are already documented in the schema. The description only restates that lookup is by key, adding no format, scoping, or edge-case detail 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?

States a specific verb and resource ('Read one memory entry by key') plus the returned fields, which distinguishes it from a bulk/search read. It never names search_memory explicitly, so the differentiation from its closest sibling is left implicit.

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

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

'by key' implies this is the exact-lookup path rather than a query, which hints at when to prefer it over search_memory. There is no explicit when-to-use/when-not guidance, no mention of prerequisites, and no named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that matching spans JSON values, descriptions and summaries, not just keys, but says nothing about match semantics (case sensitivity, literal vs. tokenized), result ordering, or how paging behaves.

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

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

A single front-loaded sentence with zero filler; every word earns its place. It is efficient, though the extreme brevity leaves the heavier scoping and paging questions unaddressed elsewhere.

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 twelve-parameter search tool with no output schema, one sentence is thin: it omits default behavior (scope defaults to active, so archived versions are silently excluded), pagination expectations, and the fact that status filtering only applies to hierarchical memories. The annotations cover safety but not the query semantics an agent needs to build a correct call.

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 twelve parameters, including the enums for tier, scope, status and memory_type, are already documented in the schema. The description merely restates the searchable fields that the `search` parameter description already conveys, adding no syntax, precedence, or combination rules (e.g. how tags, scope and search interact).

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

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

States a specific verb ("Search") and resource ("memory") plus the fields scanned (keys, JSON values, descriptions, summaries), so an agent knows exactly what is matched. However, it never distinguishes this from the sibling read_memory, so the agent must infer that one is a key lookup and the other a text 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?

No when-to-use statement, no exclusions, and no reference to read_memory as the alternative for direct key retrieval. The only guidance is implicit in the word "Search"; nothing tells the agent whether to reach for this tool when it already has a key or when it needs to page through archived versions.

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 flag destructiveHint=true and idempotentHint=true, so the safety profile is declared. The description adds singleton context ('one persona stored on the playbook'), but it does not disclose whether omitted fields are cleared or preserved — a material question for a tool marked destructive.

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

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

A single front-loaded sentence with zero waste that names the resource and its editable fields immediately. It is arguably too terse for a destructive five-parameter tool, but nothing in it is 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 destructive mutation with a nested metadata object and no output schema, the description omits what happens to unspecified fields, whether metadata is merged or replaced, and what the response looks like. The singleton note helps but does not cover the destructive semantics an agent needs before invoking.

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 five parameters are documented in-schema, and the baseline is 3. The description restates three editable fields (name, system prompt, metadata) but adds no syntax, format, or merge/replace semantics beyond the schema.

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

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

States a specific verb and resource ('Edit the playbook's one persona') and enumerates the editable fields, so the agent knows exactly what is mutated. It also calls out the singleton nature of the persona, which no sibling tool covers. No sibling differentiation beyond that, but none of the listed siblings is persona-related.

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 playbook's one persona' implies this edits an existing persona rather than creating one, which is useful framing, but there is no explicit statement of when to use this versus fetching a playbook or when it would fail. Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds useful nuance by saying 'fully replace,' clarifying that existing content is overwritten. However, it does not mention permissions, side effects, or whether the operation creates a new document when the slug is absent.

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

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

The description is a single tight sentence with zero waste. The core action and replacement semantics are 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?

With six parameters, required run and playbook identifiers, and no output schema, the definition is minimally viable but thin. An agent can invoke it using the schema, but the description does not explain return behavior, slug uniqueness, or what happens when replacing an existing document.

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 six parameters are already documented in the input schema. The description adds no parameter-specific detail beyond the general notion of writing a canvas document, which is acceptable given the full schema coverage.

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

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

The description states a specific verb and resource: create or fully replace a canvas document. It is clear what the tool does, but it does not explicitly differentiate from sibling tools like read_canvas or list_canvas.

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

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

There is no guidance on when to use this tool versus alternatives such as read_canvas, list_canvas, or update_persona. It also omits prerequisites like needing a valid playbook_id and run_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 destructiveHint=true and idempotentHint=true; the description adds the crucial mitigating fact that previous contents are saved automatically and retrievable via get_memory_history. That materially changes how an agent should weigh the destructive hint, which is real value beyond structured fields.

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

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

A single sentence that front-loads the upsert semantics and ends with the recovery path. Nothing is wasted and nothing is buried.

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 14-parameter tool with nested metadata and no output schema, the description covers only the core upsert and history behavior. It says nothing about hierarchical task tracking, archiving/restoration, or tier semantics, leaving the schema to carry the entire burden.

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 rich parameter set (tier, status, metadata, memory_type, is_archived, etc.) is fully documented in the schema. The description itself explains none of these semantics, so the baseline 3 applies.

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

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

States a specific verb pair (create or update) plus the resource (memory) and the keying rule ('by key'). This clearly separates it from read_memory and search_memory, though it never names those siblings explicitly.

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 upsert-by-key phrasing implies when to use it for writes, and pointing at get_memory_history gives one concrete follow-up alternative. There is no explicit guidance on when not to use it (e.g., vs update_persona or write_canvas) or on how to choose a tier.

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