pickem_pick

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

No annotations are provided, so the description carries the full burden, and it discloses the most important behavioral trait: the confirm flag gates a dry-run by default, which is a real safety mechanism an agent must understand. It does not cover auth requirements, whether an existing pick is overwritten, or error behavior, but the critical send-gate is surfaced.

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-loads the 'WRITE.' marker and the core action, then an Args block with examples. Efficient and well-ordered, though the 'may be the only way to fix an entry' sentence is slightly redundant with the no-web-interface point.

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?

An output schema exists, so return values need not be described, and the confirm/dry-run mechanism is covered. The gap is the three undocumented optional parameters (week, pickem_league, pickem_roster) with no annotations to fall back on, leaving the agent unsure whether they must be supplied for a correct invocation.

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, and it does well for three of six params (game_id with a Sleeper example, team with an abbreviation example, confirm with dry-run semantics). However, week, pickem_league, and pickem_roster are entirely undocumented in both schema and description, leaving half the parameters ambiguous.

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?

States a specific verb and resource ('Make or change one pick'em pick') and prefixes the mutation nature with 'WRITE.' It also distinguishes itself from the read sibling by directing the agent to pickem_status for game_id, so the agent can tell it apart without opening a 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?

Gives concrete operating context: get game_id from pickem_status, and confirm must be True to actually send (default False = dry run). It also notes Pick'em has no web interface, explaining why the tool exists. It stops short of explicitly naming a when-not/alternative for the write itself.

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