AgentPlaybooks

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

Annotations already establish a safe, idempotent read, so the description spends its words well on non-obvious behavior: results are tool definitions with schemas, the search surface widens with playbook_id, and pinned domain views restrict the result set. Terms like 'core/full' and 'Pinned domain views' are used without definition, which limits how much an agent can act on 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?

Four short sentences, purpose front-loaded, each carrying distinct information with no filler. Slight density cost from unexplained internal jargon ('core/full', 'Pinned domain views') that an outside agent cannot 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?

With an output schema present, the description needn't describe return values, and it instead covers the risky parts: search scope, when playbook_id matters, and whether omitted tools are callable. That is sufficient for an agent to select and invoke this 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 earns above that by explaining the semantic effect of playbook_id (it expands the search scope to connected servers) rather than restating the schema's 'UUID or GUID of the target playbook'. The limit cap is left 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+resource: find operations by keyword and return their input schemas, which is a distinct capability from every sibling (get_playbook, list_skills, list_mcp_servers are conventional lookups). It does not explicitly name a sibling to contrast with, so it lands just shy of 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?

Gives a clear conditional: omit playbook_id for the account catalog, supply it to also search connected servers. It also warns that omitted tools remain callable in core/full, discouraging the false inference that absence means unavailability. No explicit when-not-to-use-this-tool statement keeps it at 4.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered; the description adds genuinely new behavior: attachment bodies are omitted by default, include_attachments produces a complete export, and demonstrations come back with resolved recording and segment links. The only weakness is that 'Read-only' restates the annotation and no guidance is given on size/rate implications of a full export.

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

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

Front-loaded with the primary return payload, then the modifier flags, then the ID/discovery guidance, so the most important information comes first. Six sentences is dense but nearly all earn their place; only 'Read-only' (redundant with readOnlyHint) and the playbook_id restatement are filler.

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

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

An output schema exists, so return-value structure need not be explained, and the description still covers default omission of attachments, the full-export escape hatch, resolved demonstration links, and ID format flexibility. For a 4-parameter read with full schema coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: skill_id accepts either a UUID or a kebab-case name, and playbook_id is the UUID/GUID of the target playbook. It also clarifies the intent of the two boolean flags (manifest-only vs. complete export) rather than just their defaults.

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 ('Return the full definition of one skill') and enumerates what that definition comprises: SKILL.md content, metadata, attachment manifest with filenames and sizes. It also explicitly distinguishes itself from list_skills, list_skill_versions, and get_skill_reference, so an agent can select it without reading sibling schemas.

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

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

Gives explicit conditions and alternatives: use include_content=false for manifest only, use get_skill_reference to read a single attachment body, use include_attachments=true for a full export, use list_skills to discover IDs, and notes list_skill_versions is historical rather than current. Every branch point an agent could hit is routed.

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 read-only/idempotent, but the description adds substantial behavior: code-fence headings are ignored, matching is first-exact ATX heading and case-insensitive, offsets are UTF-16 units, output is capped with next_offset continuation, and the parent skill must belong to the playbook.

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 core action and its scoping constraint are front-loaded, and later sentences supply the matching, pagination, and permission rules. It is dense and packs several rules together, but no sentence is filler.

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

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

With an output schema present, the description need not describe return values, and the remaining unknowns an agent would care about — file selection, section matching, pagination, size caps, and the playbook ownership precondition — are all 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?

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining that section matches the first exact ATX heading case-insensitively with code fences ignored, and by clarifying that offsets count UTF-16 string units and chain from next_offset.

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 with scope: 'Read exactly one skill file, optionally just one Markdown heading and its subsections.' It also distinguishes itself from the sibling get_skill by directing the agent to that tool's attachment manifest as the source of filenames.

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 tells the agent where filename values come from (get_skill's attachment manifest, or SKILL.md for main instructions) and what section values must match. It does not state any when-not-to-use condition or contrast with other read tools like read_canvas, so it falls just short of full routing 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?

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/idempotent/non-destructive, yet the description still adds real behavior: content and attachment bodies are omitted by default, descriptions are capped at 512 characters, and include_content is an opt-in that enlarges discovery. The separate 'Read-only.' sentence is redundant with readOnlyHint=true, which keeps this from a 5.

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

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

Front-loaded with payload and default behavior, followed by alternatives and exclusions — good ordering with no filler sentences. It is slightly over-long because 'Read-only' and the playbook_id format duplicate structured data.

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 listing tool with a rich output schema and full annotation coverage, nothing an agent needs is missing: payload scope, defaults, alternatives, and the negative routing case are all 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 coverage is 100%, so both parameters are already documented in structured fields, and the description's 'UUID or GUID of the playbook' merely restates the schema. It does add mild value by framing include_content as an exception for an explicit full-content listing.

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 (list the skills attached to a playbook) plus the exact fields returned as metadata. It explicitly distinguishes itself from get_skill, get_skill_reference and list_skill_versions, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use routing ('Use get_skill for one definition, then get_skill_reference for one file or Markdown section') and an explicit when-not ('Do not use list_skill_versions, which lists historical revisions'). The include_content caveat further constrains usage.

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

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

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

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

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

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

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance: using get_canvas_toc to discover section IDs, using list_canvas to find slugs, and passing playbook_id as UUID/GUID. These references enrich the schema descriptions and help agents source correct parameter values.

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

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

The description clearly states the tool reads a canvas document, returns full content, section structure, and metadata, and supports optional section-level reads. This distinguishes it from siblings like get_canvas_toc and list_canvas, which are explicitly positioned as discovery helpers.

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

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

The description implies usage—read a canvas when you need full content or a specific section—and gives guidance for using get_canvas_toc to find section IDs and list_canvas to find slugs. However, it does not explicitly state when to prefer read_canvas over these sibling tools or when not to use it.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb+resource ('Read one memory entry by key and return its value, tags, tier, summary, and metadata') and explicitly differentiates from siblings search_memory, get_memory_context, get_memory_tree, and write_memory. An agent can pick it apart from siblings without opening schemas.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description opens with a specific verb and the exact fields searched ('keys, JSON values, descriptions and summaries'), and its scope semantics ('archived searches archived entries and previous versions') clearly separate it from siblings like get_memory_history and read_memory. An agent can distinguish it from the other memory tools without opening a schema.

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

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

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

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

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

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?

Annotations declare destructiveHint=true and idempotentHint=true, and the description reconciles the destructive flag by explaining previous contents are saved and retrievable via get_memory_history. It goes beyond structured fields with permission requirements (memory:write / full vs memory:propose producing a pending_review proposal) and archive/tier 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?

Front-loads the core action and follows with the highest-value policies (concise saving, dedup-by-key, archiving). It is dense and covers many concerns in one block, but nearly every sentence carries actionable instruction; minor looseness around the playbook_id sentence.

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, nested-metadata mutation with no output schema, the description covers the risky and non-obvious angles (permissions, proposals, history retention, archiving, tiers). It omits any mention of return shape and barely touches several optional parameters, but schema coverage is complete so the gap is small.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: memory_at defaults to save time and accepts ISO, is_archived toggles visibility, tier controls context priority independently of archiving, and playbook_id is UUID or GUID. It does not add guidance for tags, priority, parent_key, status, or memory_type, so it stops short of full value-add.

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

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

States a specific verb pair and resource ('Create or update a memory by key') and immediately clarifies the create-vs-update semantics that distinguish it from read_memory, delete_memory, or archive_memories. An agent can identify the operation and its target without opening the schema.

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

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

Gives explicit when-to-do-what: update an existing key rather than duplicating a contradictory fact, archive obsolete entries with archive_memories, save durable facts not raw transcripts. It names the corrective alternative (archive_memories) and the review path (memory:propose).

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