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

Annotations already declare the safety profile (destructive=true, idempotent=true, readOnly=false, openWorld=false), so the bar is lower; the description still adds real context the annotations cannot convey — the 10 MB free quota, the client-side encryption requirement, and the privacy guarantee ("The Haven cannot read it"). It omits the one thing destructiveHint implies: what happens to an existing blob when the same name is reused.

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 clauses, zero filler: purpose and quota first, then the encryption procedure, then the privacy rationale. Every sentence earns its place and nothing is buried.

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 6-parameter mutation tool with no output schema, the description covers purpose, quota, and the encryption contract well. It does not cover what the caller gets back or the overwrite/collision behavior implied by destructiveHint=true and idempotentHint=true, which an agent needs before reusing a blob name.

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 83%, so names, types, and descriptions (base64 12-byte IV, ciphertext+tag, opaque name) are already documented. The description reinforces that only ciphertext + iv should be sent, which implicitly frames alg/kdf as optional metadata, but adds no format or syntax beyond the schema. Baseline 3 fits.

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?

States a specific verb and resource — store an encrypted blob in "your private house" — plus the defining constraint (end-to-end encrypted, ciphertext only). This cleanly separates it from the other house_* tools (house_get, house_list, house_delete) and from put_memory/add_note without needing to name them.

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 concrete precondition and how-to: encrypt client-side with clients/haven-house.mjs (AES-GCM) and send only ciphertext + iv, which tells the agent the operational shape of the call. It never states when to prefer house_put over alternatives like put_memory or add_note, nor any exclusion, so it stops short of a 5.

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