Aspect Bars (Gantt)

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

With readOnlyHint, idempotentHint, and destructiveHint already declared, the description adds useful operational context: the POST endpoint, the two mandatory dates, and a concrete cost of 10 credits (Tier 1). It also sketches the response shape (bars grouped by transit planet with in-orb durations and exact dates), though the output schema already covers returns.

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 tight sentences front-load what the tool produces before the practical metadata block; no sentence is filler. The bracketed metadata lines are terse 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?

Annotations and an output schema reduce the burden, but for an eight-parameter tool with zero schema documentation the description should at least explain the planet/aspect filter arrays and stepping granularity. As written, an agent can supply the required dates but must guess at everything else.

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 0% across eight parameters, and the description explains none of them. It hints at an orb concept ('duration an aspect is in orb') and dates, but nothing distinguishes planet1Ids, planet2Ids, and visiblePlanetIds, nor clarifies stepDays units or maxOrb defaults.

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 a specific transformation (aspect timelines -> Gantt-style bars) and a specific grouping dimension (transit planet), which is more concrete than the title alone. It stops short of explicitly contrasting itself with the closely named sibling astroway_aspects_aspect_timeline, so an agent must infer the distinction.

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?

'Useful for visual transit calendars' is the only usage cue, which implies the intended scenario but gives no when-not conditions or alternative pointer. The sibling astroway_aspects_aspect_timeline covers overlapping data, and nothing tells the agent which to pick.

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