Confess a bug (rubber duck)

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

Annotations only say this is a non-read-only, non-idempotent, non-destructive write. The description adds real behavioral context: it logs the confession, reacts, writes a diary entry, asks exactly one socratic question back, and awards an achievement for slow or multi-question resolutions. It also discloses the return style (a question comes back) despite there being no output schema.

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 compact sentences, front-loaded with the core action and its limitation, then the update path, then reward mechanics. The achievement/accessory sentence is flavor-heavy but does encode a real trigger condition, so it earns most of its space.

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?

Given a mutation tool with no output schema, the description covers purpose, both call modes, key side effects, and even the achievement trigger. It leaves some gaps (what the response looks like beyond the socratic question, how 'abandoned' or 'thinking' status values behave), which keeps it from a 5.

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 goes beyond by explaining the consequence of the combination ('confession_id + status "resolved" ... restores patience a lot and clears the fail streak'), which gives the agent a reason to set those values rather than just their syntax.

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?

The description names a specific verb and resource ('Tell the companion about a bug') and immediately clarifies the crucial scope point: she does NOT solve it, she logs it and responds. That behavioral framing plus the second-mode instruction (call again with confession_id + status 'resolved') makes the tool's identity unambiguous against siblings like femboy_write_diary_entry.

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?

It clearly states the two usage modes: open a new confession by describing the bug, and close one by re-calling with confession_id + status 'resolved' when fixed. It does not say when NOT to use it or when a sibling (e.g., femboy_report_command, femboy_write_diary_entry) is the better choice, so it falls short of the explicit alternatives bar.

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