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

Annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds substantial context beyond them: monitoring starts paused, an existing live Gambit is joined rather than duplicated, retries are safe, idempotency_key reuse semantics, and no order is placed. The disclosed return fields and 409 error path go well past annotation coverage.

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 purpose and scope, and every clause carries operative information (auth requirement, id format, retry behavior, error path, return fields). It is dense in a single long paragraph rather than broken into scannable segments, which slightly hurts navigation but not signal.

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?

With no output schema, the description carries the full return contract (case_id, created/joined, state, monitoring_status, monitor_interval_minutes, app_url) and the failure mode (409 with code and choices). Nothing an agent needs to call this correctly 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 75% and the schema already documents id, target_case_id, and idempotency_key; the description still adds value by tying scenario_id to the 'scenario:…' prefix from get_opportunity_detail and explaining that target_case_id originates from a 409's choices array. opportunity_id's origin partly duplicates the schema text.

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 precise verb+resource ('Track a Today's Market opportunity as one of YOUR Gambits') and immediately distinguishes itself from siblings by noting it is 'the same action as Track in the Gambit app' and that it places no order, unlike order-oriented siblings. An agent can separate it from create_gambit, evaluate_opportunity, and get_opportunities without opening schemas.

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 routes the agent: opportunity_id comes from get_opportunities, scenario_id from get_opportunity_detail, monitoring is turned on via update_gambit_monitoring, and case_id is passed to get_gambit. It also handles the ambiguous case (409 tracking_target_required) with a concrete next step (ask the user, then call with target_case_id).

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