claim_chat_post

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

With annotations that only establish this is a write (readOnlyHint false), the description usefully adds that the action reserves rather than posts and warns against duplicate claims. However, it does not explain what happens after the reservation, whether the claim expires, or how duplicate requests are handled beyond the warning.

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 short sentences, with the primary action and precondition in the first and a critical duplicate-prevention warning in the second. There is no filler and the most important behavioral constraint is front-loaded.

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 with no output schema and a single undocumented parameter, this description leaves key invocation details unstated: what request_id refers to, how a claim is created or observed, and what the caller should expect in response. The precondition and duplicate warning help, but an agent lacks enough information to use the tool correctly in a multi-step flow.

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?

The schema has 0% description coverage and the description never mentions request_id, so the string parameter's meaning is only inferred from its name. The warning about existing claims hints that request_id may identify a prior claim, but the description does not explicitly connect the parameter to the claim or say where the ID comes from.

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 the action ('Reserve') and the object ('one browser submission') and adds a precondition ('after user authorization'), which makes it distinguishable from sibling posting/preparation tools. The phrase 'browser submission' is somewhat jargon-heavy but does not obscure the core claim/reserve semantics.

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 explicit guidance not to call this when a claim already exists ('Never resubmit an existing claim') and sets an authorization precondition. It does not name alternatives such as post_league_chat or prepare_chat_post, so an agent must infer when this tool is the right choice rather than being told.

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