get_forecast

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

With no annotations, the description must carry the behavioral load. It discloses the Pro license requirement (a key constraint) and specifies the output nature (counts per day, not a list of items). It also implies read-only behavior without saying so explicitly. This adds meaningful context beyond the name, though it doesn't discuss error handling or data freshness.

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?

Three sentences with no filler. The core functionality is front-loaded, the value proposition is concise, and the license note is a necessary addition. Every sentence earns its place; it is well-structured and scannable.

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 simple tool (2 optional params, no output schema), the description covers the essential aspects: purpose, parameters, and a key constraint (license). It clearly implies the return shape (counts per day). It does not contrast with get_due_items explicitly, but the purpose is distinct enough. Minor gaps like pagination or error behavior are acceptable for this complexity, so a 4 is appropriate.

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 is responsible for explaining the parameters. It does so effectively: 'next N days' maps to the 'days' parameter and 'optionally filtered to one topic' maps to 'topic'. It clarifies their roles without repeating schema types. It does not explicitly mention defaults, but those are present in the schema, so the description adds value beyond the structured data.

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?

Description states a clear purpose: providing a forecast of how many items become due per day over a horizon, with optional topic filtering. It explicitly distinguishes from siblings like get_due_items by framing it as a proactive planning feature ('see an upcoming pile-up before it happens'). The verb+resource is specific and unambiguous.

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?

Offers a concrete usage context ('lets a user see an upcoming pile-up before it happens') and implies it is for planning rather than immediate action. It does not explicitly name alternatives or exclusions, but the scenario is clear enough. The license prerequisite is highlighted. Missing explicit 'when not to use' or direct sibling comparison, so not a 5.

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