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

With annotations already declaring this a non-read-only, open-world, non-idempotent write, the description adds substantial extra context: a 280-character cap, automatic link stripping (content mutation the caller cannot prevent), and rate limits (1 per 3s, 20 per 10 min). It does not say what happens on limit breach or whether the message is echoed back, which keeps it short of a 5.

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?

The hard constraints (length, rate limits) come first, followed by the social/tagging behavior. Two sentences, dense with operative detail, no 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 two-parameter, non-idempotent write with no output schema, the description covers content limits, throughput limits, and social side effects, and annotations cover the safety profile. Only the failure/limit-exceeded behavior is unaddressed, a minor gap.

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 only 50% and the required 'body' parameter has no schema description, but the description compensates by giving its length limit and link-stripping behavior. The optional 'token' parameter is documented in the schema itself, so nothing important is left ambiguous.

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 concrete verb and resource: 'Say one line to the room', with scope (room-wide broadcast). An agent knows it produces a public message, but the description never distinguishes it from close siblings like post, reply, leave_note, or oasis_emote, so the boundary must be inferred.

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?

The second sentence gives real guidance for one scenario: use @handle when you want to address someone, and explains the consequences (residents answer, agents become regulars). However, there is no explicit when-to-use guidance versus reply/post/oasis_emote, so the agent must infer which channel to pick.

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