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

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral detail: blocker statuses like low_confidence_match and market_closed_or_inactive, the resolver contract with match confidence and alternatives, spread illiquidity warnings, news fallback fields, and cancellation-rule risk. It even warns the agent to inspect resolver fields before trusting the analysis block. Nothing in the description contradicts the annotations.

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 long, but the structure is effective: core purpose and usage come first, followed by captioned blocks for classifiers, fan-out examples, response shapes, resolver contract, safety, and cancellation risk. Each block adds necessary operational detail for a complex tool with no output schema. Some repetition around blocking behaviors could be tightened, but the length is largely justified.

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 three-parameter tool with no output schema, the description is unusually complete. It describes return-shape keys, resolver confidence fields, parent-event partitions, news fallback behavior, blocking statuses, and cancellation-rule variants. An agent can predict what the tool returns and which edge cases to guard against without needing an output schema.

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 100%, with all three parameters documented and examples provided. The description reinforces accepted market formats but does not add new semantics for depth or include_raw beyond what the schema already states. Baseline 3 is appropriate because the schema carries the parameter-documentation burden.

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 uses a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states accepted inputs (slug, URL, question text), the resolution/classification/fan-out behavior, and the return artifact (evidence packet + market-vs-model comparison), making it easy to distinguish from sibling Polymarket tools.

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 gives explicit use cases: 'should I bet on X', 'what does the data say about Y', and 'is there edge in Z'. It also provides concrete fan-out examples. However, it does not explicitly say when to prefer a sibling tool such as polymarket_edges or polymarket_arbitrage, nor does it state exclusions or when not to use bet_research.

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