telys_compact

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, and the description enriches them with the exact mechanics (tombstone flush, delta merge into base), a persistence guarantee ('the store is persisted'), idempotency behavior ('Repeating with no pending changes is a no-op'), and the failure mode. 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 compact, with each clause earning its place: core operation, when to use, alternatives, required parameter, idempotency behavior, and failure condition. The primary action is front-loaded 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?

For a single-parameter, no-output-schema maintenance tool with rich annotations, the description covers operation, trigger condition, alternatives, persistence, no-op behavior, and error semantics. Nothing an agent needs to call 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 schema already documents the single `collection` parameter, setting the baseline at 3. The description adds a small amount — the 'Required' reminder (redundant with the schema's required field) and the failure condition ('Fails when the collection does not exist') — which gives error expectations but doesn't substantially extend what the schema already 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 names specific verbs and resources ('Flush tombstones and merge the delta segment into the base layout, physically reclaiming space from deleted/updated rows'), precisely identifying the operation and its effect. It also distinguishes itself from siblings by naming telys_delete and telys_tune as alternatives, so an agent can differentiate 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?

Gives an explicit trigger condition ('Use after large delete or update batches'), names alternatives with their distinct purposes ('telys_delete to remove rows, telys_tune for index tuning'), and states the no-op case for repeated calls. This fully routes an agent's decision between this tool and its siblings.

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