List current SpicyAPI key tasks

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior, and the description adds meaningful behavior beyond that: metadata-only responses, UTC half-open date intervals, defaults and maximums, stable cursor requirements, exact-but-settled cost semantics, and explicit non-polling/non-prerequisite characteristics. No contradiction with 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?

Every sentence carries a distinct, useful fact: scope, date semantics, pagination rules, limits, cost behavior, sibling routing, and exclusions. The core purpose is front-loaded, and the later caveats build context without repetition or padding.

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 output schema covers return shape and annotations cover safety/idempotency, the description supplies the remaining operational context: current-key scope, metadata-only behavior, date boundaries, cursor stability, limit defaults, cost finality, and clear exclusions. The only minor omission is explicit model/state filter semantics, but the schema names and enum mitigate that.

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 0%, so the description must compensate. It adds concrete semantics for from/to (UTC, half-open interval, default/max), limit (default/max), and cursor (fixed across pages), but it does not explicitly explain the model or state filter parameters. The state enum is self-describing and model is inferable, but the description is not fully exhaustive.

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 identifies a specific verb and resource ('Discover current-key task history') and adds the crucial qualifier 'with metadata only, without fetching each result.' It also differentiates itself from task_get and usage_get, so an agent can distinguish it from siblings 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?

The description gives explicit routing guidance: use task_get only for selected results and usage_get for settled spending including hidden tasks. It also preempts misuse by stating this is not a polling endpoint or a prerequisite to generation, plus gives pagination and date-window instructions.

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