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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: determinism ('no AI'), a concrete credit price (20, Tier 2), and the note that every candidate is rescored, which tells the agent the call is not free to spam. That pricing/determinism detail is exactly the kind of thing annotations cannot carry.

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 compact but written as one long parenthetical-heavy run-on, with the operative framing ('what does it return, what do I get for 20 credits') only arriving at the end. The jargon clauses ('planets with Rahu and Ketu, BPHS planetary friendship', 'his harmony groups') are informative but bloat the front of the sentence where the agent's routing decision happens.

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 shapes need not be described, and the required name/date plus endpoint and tier are supplied in the metadata block. With the candidate-generation rules, the dual-convention reading and the cost all disclosed, an agent has enough to call this correctly; only the absence of sibling routing keeps it from being fully complete.

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 high (83%), so the schema already explains limit, fields, precision and the convention enum. The description still adds real meaning the schema does not: 'the current name is read under both', which clarifies that `convention` selects which convention picks candidates rather than restricting the baseline analysis. That nuance materially changes how an agent sets the parameter.

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 resource and operation: the name number under Chaldean and Cheiro, its compatibility with driver/conductor numbers, plus candidate respellings that land on a favourable number. It also implicitly separates itself from the many plain numerology siblings by being a 'correction' tool that generates candidates rather than reading a single number. It stops short of naming a specific sibling alternative, but the purpose is unmistakable.

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?

Usage is only implied: an agent can infer this is for 'fix my name so the numbers are favourable' and that `convention` defaults to chaldean. There is no explicit when-to-use or when-not, and no routing to plausible alternatives such as astroway_business_name_suggestions, astroway_vedic_muhurat_name_change, or the plain chaldean/cheiro chart tools that would be used if only the number itself were wanted.

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