store_purge_collection

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

Exceptional, going far beyond the binary destructiveHint=true annotation. It discloses the mechanism ('records are retained (deleted=1) and stay recoverable'), the user-visible effect (records 'fall out of get/list/search'), and — crucially — the non-effects ('store.db is never removed', 'hard removal is an operator/filesystem act, deliberately outside the tool surface'). The confirm guard protocol and store_scope boundary are exactly the operational details an agent needs to safely invoke a bulk destructive call.

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?

Five dense sentences, front-loaded with the most important fact, each covering a distinct concern: what it does, how the soft-delete behaves, what it deliberately does not do, the safety guard, and the scope boundary. Zero filler — every clause climbs over the previous one's information gain.

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 bulk operation with no output schema and no schema descriptions, this covers all the operational ground: recovery semantics, effects on queries, the confirmation protocol, non-destruction of the db file, and scope confinement. Nothing an agent needs to invoke or recognize the danger of this tool 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 description coverage is 0%, so the description carries the full burden — and largely compensates. It explains the non-obvious confirm parameter precisely ('pass confirm=<collection name> to proceed') and repeatedly clarifies the collection parameter's scope (whole collection at once, per-store_scope). app_id is never mentioned, so the compensation is strong but not complete.

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, resource, and scope: 'Soft-delete EVERY record in a collection at once.' It positions itself against a named sibling ('a bulk store_delete'), making the bulk-vs-single distinction unambiguous. The 'EVERY...at once' cardinality and explicit tie to the store's soft-delete model fully disambiguate it from every other store_* tool.

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?

Names a concrete use case ('clearing out a whole collection (e.g. leftover test/scratch data)') and frames itself explicitly as the bulk variant of store_delete. What is missing is an explicit when-not-to-use routing such as 'for a single record, use store_delete instead' — the sibling differentiation is strongly implied but never spelled out as a decision rule.

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