calculate_aspect_windows

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: server-side checks gate successful results, summary mode truncates to five rows with marked truncation while preserving scalar lists, and verification references always describe the complete calculation. These are exactly the non-obvious behaviors an agent needs.

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?

Front-loads what the tool computes, then requirements, then verification workflow, then verbosity controls — a sensible order. Some slack exists: 'Server checks run before successful results are returned' is vague, and the closing line restates the schema's statement that references identify the full calculation.

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 still conveys the shape of each returned aspect (orb window, elapsed, remaining) and how summary mode alters it. That is sufficient for correct invocation, though it never mentions counts, ordering, or pagination limits beyond the five-row preview.

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 50%, and the description compensates precisely: moment is ISO 8601 with a timezone offset defaulting to now, location_id is required for a stated reason, and include/detail_level interactions are clarified. It supplies the semantics missing for the two undocumented parameters rather than repeating the well-documented ones.

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?

States a specific resource and computation ('Planet-to-planet aspects in orb at one moment') plus the distinctive payload: duration in orb, elapsed, and remaining time. That differentiates it from the many render/calculate siblings, though it never names scan_planetary_aspects, the closest potential source of confusion.

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?

Gives concrete usage rules: location_id is mandatory and why (Lot of Fortune/Spirit), moment defaults to now, and it prescribes the follow-up workflow with verify_calculation_claims before interpreting. It also explains when to use detail_level=summary/include versus omitting both. Missing only explicit routing away from sibling aspect tools.

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