Travel Palace (Qianyi)

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new operational context: the endpoint path and a 5-credit cost, which helps an agent judge whether the call is worth making. It does not describe what the response contains or whether the result depends on birth data beyond the given date.

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 keyword line is front-loaded and the bracketed metadata is compact and scannable, so nothing is bloated. However, the opening line is a noun fragment rather than a usable statement of function, making the definition under-specified rather than concise.

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 values need not be explained, but the description leaves a critical ambiguity: a palace chart tool taking only a date, with no birth data mentioned, gives an agent no way to know whether this is a natal palace placement or a date-based transit reading. For a domain-specific palace endpoint among dozens of near-identical siblings, that clarification is essential.

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%: timezone and timezoneOffset are richly documented in the schema, while date and time have no descriptions there. The description's sole contribution is restating that date is required, which the schema's required array already states. It adds no format, semantics, or interpretation for the undocumented date/time parameters.

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 is a keyword fragment, 'Travel, relocation, foreign opportunities,' naming the thematic domain of the Zi Wei 'Travel Palace' but supplying no verb or statement of what the tool actually produces. The name plus title differentiate it from sibling palace tools (career, spouse, wealth), but the description itself does not add that differentiation.

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?

There is no guidance on when to call this versus astroway_ziwei_chart, astroway_ziwei_twelve_palaces, or the other palace endpoints. The only implied usage cue is the '[Required: date]' tag, which is not a when-to-use instruction.

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