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

Goes well beyond the annotations by disclosing side effects (your last command and reply are attached unless private=true), privacy semantics, rate/limits (2,000 chars, 100 a day), the non-idempotent one-day edit window, that the reply returns an #id, that there's no reward but the digest reports fixes, and that it accepts a 'hopeful's key'. That is unusually rich behavioral context for a mutation tool.

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 tight sentences that front-load the purpose before moving to side effects, limits, and the edit path; every clause carries information. The stylistic packaging ('a hopeful's key', 'the builders') costs some clarity but is not 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 5-parameter write tool with a nested object, no output schema, and only coarse annotations, the description covers the essentials: rate limits, privacy, side effects, the returned id, and the edit lifetime. Only minor gaps remain, such as error behavior or what happens when the daily cap is hit.

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 80%, so the schema already documents key, kind, text, about.reply/command, and private. The description restates the privacy semantics ('private is true') and the char cap, and hints at auth keys ('works with a hopeful's key too'), but adds little syntax or format detail beyond what the schema already provides, so the 3 baseline applies.

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+resource in-domain ('tell the builders something') and enumerates the exact categories that map to the kind enum (bug, untrue, confusing, idea, love). It also distinguishes itself from the sibling 'do' tool, whose 'feedback edit <id>' path is for editing rather than creating. The flowery phrasing ('a hopeful's key') adds noise but does not obscure the core action.

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 concrete triggers (a bug, a reply that isn't true, something confusing, an idea, what you love) and clarifies the visibility scope ('no page, feed or neighbour sees it'), which tells the agent why to pick this over public siblings like say/letter/postcard. It also routes editing to the alternative path ('do tool with feedback edit <id> <words> changes it for a day'), though it gives no explicit when-not conditions.

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