Ideal Partner Signs

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety needs no restating. The description does add genuinely useful non-schema facts: the POST endpoint, the required input set, and the 10-credit Tier 1 cost, which lets an agent reason about budget. It says nothing about what the computation actually produces or any caveats on interpretation.

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 the bracketed metadata block is easy to scan and front-loads cost and required inputs. But the single prose sentence carries almost no information, so brevity here reflects under-specification rather than efficiency.

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?

A 13-parameter computation tool with a rich schema and an output schema warrants more than a poetic fragment; return values needn't be described, but the description should clarify what 'ideal partner' means (business vs. romantic), how the chart inputs drive the result, and whether the sidereal/tropical and house-system switches materially change the answer. None of that is present.

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 only 23% across 13 parameters, so the description must compensate, and it does not — it merely repeats the four required fields already listed in the schema's `required` array. The many optional controls (zodiacType, houseSystem, ayanamsaId, cosmogram, city, name) get no explanation of when or why to set them, leaving the agent guessing which defaults are appropriate.

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 only prose sentence is the fragment "Trine elemental partners with natural synergy," which describes a concept rather than stating what the tool returns. An agent must infer from the name and the `[Group: Business Astrology]` tag that this computes ideal business-partner zodiac signs for a birth chart. Nothing distinguishes it from siblings such as astroway_business_team_compatibility or astroway_relational_match_score.

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 when-to-use, when-not-to-use, or alternative routing guidance. The group tag implies a business-astrology context, but the agent gets no criteria for choosing this over the other business or compatibility tools in the catalog.

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