propose_trade

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

With no annotations, the description carries the burden and does well: it discloses that this reaches a real person, that acceptance can execute instantly in certain leagues, and that confirm=False is a dry run. It omits auth requirements and any rate or idempotency notes, but the key side-effect risk 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 operation type and the risk warning before the argument list; every line earns its place with no redundant restatement of the schema.

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 7-parameter mutation tool with an output schema and no annotations, the description covers the action, the critical league-dependent risk, and most parameters. The only gaps are the two undocumented internal ID parameters and any post-send return expectations, which the output schema addresses.

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: it documents give_players (from your roster), receive_players (from theirs), with_manager, faab, and confirm's dry-run semantics. Only league_id_ and roster_id_ are left unexplained, which are likely context-injected defaults.

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 specific verb+resource (offer a trade to another manager) and flags it as a WRITE operation. It is distinguishable from siblings like respond_trade or cancel_claim, though it does not name those alternatives explicitly.

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?

Explicitly tells the agent to consult league_info for trade_review_days and explains the consequence when it is 0 (executes immediately, no vote, no veto window). It also states the confirm-default-dry-run condition, giving clear when-to-send guidance.

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