recommend_draft

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

Annotations are all false, so the description carries the full burden of behavioral disclosure. It explicitly states side effects: 'Appends a calculation evidence record, including discarded work, without changing rosters or submitting picks.' It also mentions that 'current checks revision and snapshot freshness after calculation, but does not grant action permission.' This discloses non-mutating behavior and a persistent side effect, though it does not detail whether repeated calls are safe beyond not changing rosters, which is a minor gap.

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 compact at four sentences, with the main action front-loaded in the first sentence. It then covers alternatives, prerequisites, output/status, and side effects in a logical order. Each sentence adds meaningful information without fluff, though it is slightly longer than strictly necessary.

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?

Given the tool's complexity, the presence of an output schema means the description need not detail return values. It covers prerequisites, alternatives, side effects, and statuses (ready, stale_snapshot, incomplete_snapshot, roster_complete). It also notes that the tool does not grant action permission, which is crucial for agents. Nothing essential 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 coverage is 100%, so the schema already documents both parameters. The description adds value beyond the schema by explaining seed reproducibility: 'Reuse an integer with identical inputs to reproduce the simulation. This does not remove forecast uncertainty.' It also clarifies trial limits: 'Use 1 through the configured limits.batch_trials, at most 500.' This enriches the agent's understanding of how to use the parameters.

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 specific action: 'Run one bounded draft simulation against the current imported draft snapshot.' It also distinguishes from siblings by explicitly naming alternatives: 'Use start_draft_monitor for repeated batches or get_draft_recommendations to read that monitor's cached results.' This leaves no ambiguity about what the tool does and how it differs.

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 provides explicit when-to-use guidance: 'Run one bounded draft simulation' and when not to: 'Use start_draft_monitor for repeated batches or get_draft_recommendations to read that monitor's cached results.' It also lists prerequisites: 'Requires draft data with consistent pick history and full-season projections for available and selected-team players.' This is thorough and actionable.

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