squiggle_tips

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

The description adds behavior beyond the annotations by explaining that 'correct is null until played' and that 'confidence is a %, bits is the model's information score'. It also flags that a whole season is ~100 KB via the round parameter, which sets an expectation for payload size. Annotations already declare read-only/idempotent, and the description doesn't contradict them.

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 and front-loads purpose, followed by a structured return block, example, and auth note. The 'Also answers this: apisports_football_predictions' feels slightly cryptic but is not fluff; overall it's efficient and well-organized.

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 compensates by listing return fields with explanations and giving a concrete example. It covers auth, example, and key behaviors, though it doesn't mention pagination or error handling. For a read-only tool with 6 clearly-described parameters, this is adequate and above minimum.

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% and every parameter has a description, so the baseline is 3. The description adds an example call but doesn't elaborate on individual parameters beyond what the schema already provides; it focuses on the return shape instead.

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 opens with a specific verb+resource: it explains exactly what the tool returns ('What each model tipped for a game') and lists key fields (winner, margin, confidence, correctness). This clearly distinguishes it from sibling squiggle tools like squiggle_games or squiggle_sources, which handle games and model metadata respectively.

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?

It provides a concrete example for a common use case ('Every model's tips for round 1, 2026') and notes that no auth is needed. It also hints at an alternative by stating 'Also answers this: apisports_football_predictions', which helps route similar questions. However, it doesn't explicitly say when to prefer this over squiggle_games or other prediction-related tools.

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