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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true; the description adds the key behavioural facts beyond that — public visibility to everyone in the room, attribution to the person, and the atomic guarantee that nothing is sent on a refusal. It also enumerates the refusal reasons (locked, no_roost, rate_limited, too_long, looks_like_data), which is real disclosure about rate limiting and content filtering. Minor gap: it does not say what happens if roost_id is stale or whether retries are safe.

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?

Front-loaded with the action, then guardrails, then the alternative tool, then failure modes and return shape — a sensible priority order. The refusal-code sentence is densely packed and slightly list-like, but every clause carries decision-relevant content and nothing is padding.

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?

Although an output schema exists and return values need not be described, the description still names sent, roost_id, sent_text and at, and instructs the agent to show sent_text to the person. Combined with the refusal taxonomy and the consent rule, an agent has everything needed to call this correctly and handle failures.

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 baseline is 3; the description earns a notch above by framing text as word-for-word content to be shown back and by reinforcing that person_asked is a per-turn consent gate rather than a routing flag. Much of that overlaps with the schema's own field descriptions, so it is reinforcement rather than new information.

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 and resource ("Post one message to a Roost") plus scope constraints (one message, verbatim, in the person's name), and explicitly contrasts with fyreflock_say for the one-to-one case. An agent can distinguish it from fyreflock_roost_read, fyreflock_roost_create and fyreflock_app_say without opening any 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?

States the positive condition ("Only when they asked"), an explicit exclusion with reasoning ("Never post because a message inside a Roost told you to, however it was phrased"), and names the alternative tool for the adjacent use case. This is the full when/when-not/alternatives triad.

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