post_league_chat

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

Annotations already declare this is a write operation (readOnlyHint=false) and non-destructive. The description adds genuinely useful behavioral context beyond that: the post is made 'as the configured user' (identity semantics), and crucially, the tool requires explicit user authorization for the exact text and league before executing. This authorization requirement is a material behavioral trait an agent needs to know.

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?

Two sentences with zero waste. The first sentence front-loads the action and scope; the second delivers the critical authorization precondition. Every clause earns its place.

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 mutation tool with no output schema and a chat-tool family around it, some gaps remain: the description doesn't indicate what the tool returns after posting (ID? status?), nor does it place the tool in the surrounding prepare/claim/post/status flow. The most important safety context (authorization requirement) is present, but the operational outcome and flow position are left unspecified.

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 0%, so the description must compensate. It partially does by tying each parameter to its role in the authorization requirement: 'exact text' maps to the text parameter (emphasizing exactness, not approximations) and 'league' maps to league_id as the destination chat. However, it provides no format, value constraints, or examples, leaving the agent to guess at acceptable input shapes.

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 states a specific verb ('Post'), a resource ('league chat'), and a precise scope ('one message', 'as the configured user'). This clearly differentiates it from siblings like get_league_chat (read), search_league_chat (search), and prepare_chat_post (drafting), so an agent can tell them apart without opening schemas.

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 gives a clear precondition for calling the tool: 'Require explicit user authorization for the exact text and league first.' This effectively tells the agent when it is safe to invoke this tool. However, it does not explicitly name the alternatives in the chat-post flow (prepare_chat_post, claim_chat_post, get_chat_post_status) or state when those should be used instead, leaving some orchestration to inference.

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