compact_skill_memory

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes further by disclosing exactly what is destroyed ('replaces every entry up to `up_to`'), what survives ('entries added after that read are kept'), and that it is 'irreversible for the replaced entries.' That is the precise concurrency/retention semantics an agent needs before invoking a destructive mutation.

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?

Well front-loaded: behavior first, boundary/destructiveness second, then a compact Args block. A few words are slightly redundant (e.g., 'The skill whose memory to compact'), but nothing is wasted given the destructive nature of the 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?

For a 3-parameter destructive mutation with no output schema and no annotation-covered return semantics, the description supplies everything needed: purpose, prerequisite read, retention boundary, irreversibility, and the danger of the optional parameter. No output-schema explanation is needed since the tool's effect is fully described.

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 0%, so the description must carry all parameter meaning, and it does: skill_id (target), summary (the distilled durable lessons), and up_to (provenance from get_skill_memory's `as_of`, plus the consequences of omitting it). Only the concrete type/format of `up_to` (integer sequence vs. timestamp) is left implicit, which is minor.

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?

Opens with a specific verb and resource: 'Replace a skill's memory entries with one summary entry,' and adds the triggering condition '(for a memory that is full).' An agent can immediately distinguish this from append_skill_memory (which adds) and from get_skill_memory (which reads) without consulting 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 a clear use condition ('for a memory that is full') and names the prerequisite tool: `up_to` must be the `as_of` from a get_skill_memory read, with the explicit warning to omit it 'only to replace every entry.' It does not explicitly contrast with append_skill_memory as the non-destructive alternative, which is the one remaining gap.

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