Property Palace (Tianzhai)

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, openWorld=false, so the safety profile is fully covered by structured data. The description's genuine addition is the operational metadata: the Zi Wei Dou Shu group, the POST /v1/ziwei/palace-property endpoint and, most usefully, the 5-credit (Tier ½) cost, which lets an agent reason about budget. It says nothing about how the palace is derived or what the reading emphasizes beyond three topic words.

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?

It is short and front-loads the topic keywords, but roughly half the text is bracketed scaffolding (group, endpoint, required, cost) rather than substantive description, and the opening line is a noun list rather than a sentence. Brevity here reads as under-specification rather than discipline.

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?

This is one of twelve palace tools in an extremely dense suite, and the description gives an agent almost nothing to distinguish it besides three keywords. An output schema exists, so return values need not be explained, but for an input that requires a correctly formatted date (and benefits from time/timezone), the definition omits any guidance on what makes a valid or meaningful request.

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 have long, careful descriptions in the schema, while date and time carry only regex patterns. The description repeats 'Required: date', which is already in the schema's required array, and adds nothing about the date/time semantics (e.g., birth date vs. event date, whether time is optional for a valid palace). With the complex parameters already documented in structured data, baseline 3 fits.

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 ('Real estate, family home, ancestry.') with no verb and no statement of what is produced. The name and title ('Property Palace (Tianzhai)') carry most of the meaning, and together with the sibling names an agent can infer this is the Zhai palace reading of a Zi Wei chart, but the description itself never says so.

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 statement of when to use this palace versus astroway_ziwei_twelve_palaces, astroway_ziwei_full_chart, or astroway_ziwei_palace_wealth (a different house that also concerns assets). No preconditions are given (e.g., that a birth date, and preferably a birth time, is needed to place the palace). Only the mechanical notes 'Required: date' and the credit cost appear.

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