send_post_as_user

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

With no annotations provided, the description carries the full burden of behavioral transparency. It discloses that the tool sends as user identity and that @-mentions trigger notifications. However, it does not mention whether the operation is destructive (it creates a message, which is a mutation), any required permissions, rate limits, or what happens on failure. The description adds moderate value beyond the raw action.

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 description is two sentences, directly front-loaded with the main action and key features. Every sentence serves a purpose, with no redundancy. It is appropriately sized for the tool's complexity, though a slightly more structured format could improve readability.

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 the absence of an output schema and annotations, the description should provide more context. It lacks information about return values (e.g., message ID), error handling, or any side effects beyond @-mentions. For a message creation tool, this is a notable gap, making it less complete.

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 description coverage is 100%, so the input schema already provides thorough documentation for all 4 parameters, including detailed element types for paragraphs. The description adds marginal value by summarizing 'rich text' and 'real @-mentions', but does not explain chat_id or root_id beyond the schema. Baseline score of 3 is appropriate.

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 clearly states the tool sends a rich text POST message as a user, with title and formatted paragraphs, and supports @-mentions. This distinguishes it from sibling tools like send_message_as_bot, which sends as a bot, and send_card_as_user, which sends cards. The verb 'send' is specific, and the resource is well-defined.

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 description does not provide guidance on when to use this tool versus alternatives. It lacks explicit when-to-use or when-not-to-use instructions, and does not mention trade-offs with other messaging tools among the siblings. Users must infer usage from the purpose alone.

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