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

Even with annotations (idempotentHint, openWorldHint), the description adds substantial behavioral context: it returns a download_url, populates a server-side cache, defaults to summary_only=True, warns about token size, lists drill-down resources, and explains that empty descriptions are intentional. This goes far beyond what annotations provide and sets clear expectations for side effects and output format.

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 well-structured with a bold lead instruction, a contract block, and bullets for drill-down resources. Every sentence adds critical information—front-loaded with the main purpose and warnings, followed by operational details. The formatting makes it easy to scan despite its length.

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 tool's complexity, the description covers all necessary aspects: purpose, usage alternatives, contract requirements, defaults, output resource URIs, date format, and a note on empty descriptions. The output schema likely covers exact return fields, so the description does not need to repeat them. This is a complete and self-sufficient description.

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 only 20%, so the description must compensate. It does well for summary_only, explaining its default and token implications, and for start_date/end_date by specifying ISO format and range effects. However, it does not explain the `data` or `name` parameters beyond what the schema already provides. The schema itself has a descriptive note for `data`, but the description could have added more clarity on how birth data affects the calendar generation.

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 'Authoritative astrological calendar generator' and explicitly lists the use cases: 'calendar of sabbats, moon phases, retrograde stations, ingresses, or transits.' It further distinguishes itself by warning against code_interpreter, making the scope and verb clearly specific. This clearly differentiates it from sibling tools like birth_chart or get_aspect.

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 provides explicit when-to-use guidance: 'always use this tool when the user asks for a calendar of...' It also gives an exclusion: 'DO NOT compute these yourself in code_interpreter; you do not have Swiss Ephemeris and your output will be factually wrong.' Contract rules about not regenerating, not producing CSV, and not transcribing events give clear operational guidance.

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