Chart Element Interpretation

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world, non-idempotent), so the bar is lower. The description adds genuinely useful information beyond them: this is an AI generation call costing 100 credits (Tier 4), which matters precisely because idempotentHint=false means repeated calls bill again. It still doesn't say whether the response is cached or how long generation takes.

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 short lines, front-loaded with purpose, followed by structured tags for group, endpoint and cost. No wasted prose; each line earns its place.

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?

An output schema and rich parameter descriptions are present, and annotations cover safety, so much is already handled. However, the core selector — which planet, house, or aspect to interpret — is neither in the description nor documented in the visible schema, leaving a functional gap for an agent trying to call it correctly.

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 100% and the nested birth-data schema is exceptionally well documented (timezone, ayanamsa, houseSystem letters), so the baseline of 3 applies. The description adds nothing about parameters — notably it never explains how the 'single chart element' (planet/house/aspect) is designated in the request body.

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 verb+resource: AI interpretation of a single chart element (planet/house/aspect) in context, which is more granular than the whole-chart sibling ai_interpret_natal. It does not explicitly distinguish itself from ai_interpret_placement or ai_interpret_transits, so the sibling boundary is left to inference.

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 chart-detail pages" gives a usage context, but there is no explicit when-to-use vs when-not guidance and no named alternative among the many ai_interpret_* siblings. The agent must infer the choice from the word 'single element'.

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