vacuum_embeddings

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

The description asserts the operation is 'Safe and idempotent,' but the annotations declare idempotentHint=false and destructiveHint=true. The idempotency claim directly contradicts the structured metadata, and calling a row-deleting operation 'safe' undercuts the destructiveHint. This is an annotation contradiction.

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?

Three short, front-loaded sentences: the action first, then safety/scope, then the migration use case. Every sentence carries information and nothing is repeated from structured fields.

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, non-idempotent cleanup tool with no output schema, the description explains what is removed and why, which is the core need. But it leaves the sole required parameter undocumented and its safety framing conflicts with the annotations, so an agent lacks a trustworthy behavioral picture.

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 only parameter, 'vault', has 0% schema description coverage and is never mentioned in the description. The agent is told what vacuuming does but not which vault to target or what form that identifier takes, so the description does not compensate for the schema gap.

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?

Names a specific verb (drop) and resource (orphaned embedding rows) with the exact condition that qualifies them (chunk_id no longer present in the chunks table). An agent can distinguish this cleanup operation from sibling search/read/write tools 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 a clear triggering context: run it after migrations from pre-v0.7.0 schemas where chunk deletion did not cascade. It does not, however, state when NOT to run it or name an alternative cleanup path, so it stops 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.