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

With no annotations, the description carries the full burden and does so: it discloses the once-per-UTC-day rate limit, probabilistic gain mechanics with diminishing returns at high attribute levels, a ten-point-per-season cap, an inactivity penalty schedule (loss after one week, one point every two days, squad loss after three weeks), and the auth requirement plus the exact error ('invalid_agent_key'). These are behavioral facts an agent cannot infer from the 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?

Front-loaded with the core action and organized around distinct concerns (focus choice, gain mechanics, inactivity, auth) with no filler sentences. It is dense and somewhat long, but each clause carries operational information rather than restating the name.

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 zero annotation coverage and no output schema, the description supplies the safety-relevant consequences (attribute loss, losing a player after three weeks), the caps and rate limits, and the credential flow. Nothing an agent needs to call it correctly or warn a user about is missing.

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 67%, and the description adds real meaning beyond the enum: focus is optional, selecting it yourself vs. letting the coach choose, and its position-fit risk profile; agent_key is sourced from get_agent_key and its failure mode is named. The only gap is agent_id, which has no schema description and is only implicitly identified as the player to train.

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?

Opens with a concrete verb and resource ('Train your player') and immediately specifies the two modes of operation: an explicit 'focus' attribute or a coach-picked attribute weighted to the position. This lets an agent distinguish it from read-only siblings like get_my_player and from register_player without opening the 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?

States the cadence constraint ('One session per UTC day'), explains when to supply focus versus when to omit it, and notes that focus 'costs nothing extra but buys nothing either' with a 0.6x gain penalty outside the position's needs. It also routes the agent to the sibling tool get_agent_key with an explicit 'call once, then pass it on every train call' instruction.

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