List allocation days

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by explaining the return content (max_allocation plus remaining count) and the semantics of a missing allocation day, which matters because there is no output schema. It is silent on pagination/result-cap behavior for max_results.

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?

Two sentences and a short clause; the definition of an allocation day is front-loaded before the filter hints, and there is no padding. Slightly dense in the first sentence but every clause carries information.

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 read-only list tool with no output schema, the description supplies the record shape and the filtering options, which is most of what an agent needs. The main omission is behavior of the undocumented max_results cap and any ordering/pagination semantics.

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 80%, so the baseline is 3. The description restates the date/after/before and pitch_type filters but adds no format or inclusion/exclusion detail beyond the schema, and it never mentions max_results (default 500, max 3000), the one parameter with no schema description.

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 names the resource (allocation days) and precisely defines what a record contains: per date and pitch type, the maximum pitches Pitchup may sell (max_allocation) and how many remain. That is a clear verb+resource+scope, though it never explicitly differentiates itself from siblings such as check_availability or list_pitches.

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?

Usage is only implied: 'Filter by date or after/before, and by pitch type' tells the agent it can narrow results, and the note that a date with no allocation day has no allocation clarifies the data model. It stops short of stating when to reach for this tool instead of check_availability, or any when-not condition.

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