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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true. The description's "add ... or change one by its key" is consistent with upsert/idempotent behavior, but for a tool flagged destructive it never says what is destroyed when an existing board is redefined (e.g. whether accumulated scores are retained or wiped) nor what permissions are needed. It does add useful runtime context by naming the SDK call scores.submit(key, value) that fills the board.

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 create-or-modify action and the board scope are front-loaded in the first clause, and the sentence count is low. The middle list ("which way is better, how a score reads, its bounds, the wait between scores...") is a loose paraphrase of schema fields and could be trimmed without loss.

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?

The tool is a nested-object mutation with no output schema and a destructive annotation, so the description carries weight it only partly bears. It covers identity, scope, cap and runtime consumption, but leaves out what happens to existing scores on redefine, error behavior at the 20-board limit, and any indication of what is returned. Adequate but not complete for a destructive nested-parameter tool.

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?

With schema coverage at 50%, the schema still documents the nested fields reasonably well, and the description restates them in prose (order/format/bounds/cooldown/trusted) with light rewording rather than new meaning. Its one genuine addition beyond the schema is tying board.key to scores.submit(key, value), which explains why the key is constrained. The cooldown unit (seconds) and trusted behavior largely duplicate the schema text.

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?

"Add a leaderboard to one of the player's hosted games, or change one by its key" names a specific verb, resource, parent scope, and upsert semantics in one clause, and states the hard cap (up to 20). An agent can immediately separate this from the read-side sibling list_boards without opening either schema.

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 gives clear context for use: leaderboards belong to one of the player's hosted games, and the board is addressed by key, so re-calling with an existing key modifies rather than creates. It also notes the 20-board ceiling, which constrains when this tool will fail. It stops short of naming alternatives (e.g. list_boards to inspect existing keys) or stating prerequisites.

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