Promote memory

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

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

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

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

Four sentences, each earning its place: purpose, boundary/alternative, repeat behavior, and permission. Front-loaded with the core action and no filler.

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

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

For a four-parameter mutation tool with full schema coverage and annotations, the description covers the important extras: permission requirement, non-demotion boundary, sibling routing, and repeat semantics. Missing only return-value/error behavior, which is minor given no output schema.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the enum and the 0-50 range. The description reiterates playbook_id format and notes priority_boost can be repeated, but adds little parameter syntax or semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs (restore visibility, promote tier, boost priority) applied to a named resource (a memory). It explicitly distinguishes itself from archive_memories and clarifies it cannot demote, so an agent can separate it from siblings despite the crowded toolset.

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

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

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

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