12 Palaces

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive closed-world behavior, so the safety profile is covered. The description adds genuinely useful operational facts — cost of 5 credits and the POST endpoint — but says nothing about whether this computes a chart internally from the date or requires a prior chart call.

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 core sentence is one line and front-loaded with the payload contents. The bracketed metadata block is boilerplate but compact and does convey required-param and cost information, so little is wasted.

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 exists, so return shape need not be explained. However, for a 4-parameter tool whose required param is a date, the description leaves the key workflow question unanswered: is this standalone or a follow-up to astroway_ziwei_chart, and does 'date' alone produce a valid chart?

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 50%: timezone and timezoneOffset are documented in the schema, but date and time are not. The description contributes only '[Required: date]', which merely restates the schema's required array, and never explains whether 'date' is a birth date, a queried date, or the chart anchor.

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 concrete resource — all 12 palaces, including the name formats, theme and rules returned. 'All 12' signals it is the complete reference listing rather than one palace, which implicitly separates it from siblings like astroway_ziwei_palace_career, but the contrast is not stated explicitly.

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?

No when-to-use guidance is given, and no alternative is named even though a dozen single-palace siblings (destiny, wealth, spouse, career...) and astroway_ziwei_chart exist in the same group. An agent must guess whether this is the overview call or a redundant one.

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