record_pick

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

With no annotations, the description carries the burden of explaining behavior. It does mention merge behavior and ambiguous-name handling, but it does not disclose side effects, whether existing picks can be overwritten, or what errors/responses might occur.

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 concise, well organized, and free of unnecessary detail. The Args section maps cleanly to the schema parameters and adds useful guidance without bloat.

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 description provides sufficient context for typical use: when to call it, how merging works, and how ambiguous names are handled. It lacks output/error expectations and explicit differentiation from record_picks, but the core usage context is present.

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 description adds meaning to all three parameters, including acceptable formats, defaults, and the difference between player name and player ID. It does not explicitly state that player and player_id are mutually exclusive, though the phrasing strongly implies it.

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's purpose: manually recording a pick when ESPN is not reporting draft data. It also provides concrete use cases and distinguishes the action from normal draft-state retrieval.

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 explains when to use the tool (live draft reporting gaps or off-ESPN drafts) and notes how recorded picks merge with ESPN data. However, it does not explicitly differentiate this singular record_pick tool from the sibling record_picks tool, which could cause ambiguity in batch scenarios.

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