Personality Number

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds meaningful behavioral detail beyond annotations: which letters count, Y always treated as a consonant, per-name-part reduction, and preservation of master numbers 11, 22, and 33. This is precisely the kind of algorithm-level context an agent needs.

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 description is well-structured with clear sections: calculation overview, WORKFLOW, INPUT CONTRACT, DO NOT CONFUSE WITH, and a docs link. It is front-loaded with the essential calculation rule and contains no filler; the only small redundancy is restating the Y rule, but it remains useful as an input contract reminder.

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?

Given an output schema exists, the description does not need to explain return values. It covers the input contract, examples, master-number behavior, workflow placement, sibling disambiguation, and includes a URL to the full output/error contract. Nothing essential is missing for correct selection and invocation.

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 100%, so the baseline is adequate. The description enriches the name parameter with a fuller contract ('Full legal name as used at birth'), concrete examples, and the Y-is-always-a-consonant rule. However, this slightly conflicts with the schema's 'as commonly written' wording, creating minor ambiguity about which name form is authoritative.

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 opens with a specific verb and resource: 'Calculates the Personality number from consonants in the full name.' It further differentiates from the most similar siblings by naming the Expression number (all letters) and Soul Urge number (vowels only). This makes the tool's purpose unambiguous.

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?

The WORKFLOW section explicitly says the tool is standalone BEFORE and points to asterwise_get_numerology_profile AFTER for seeing all five core numbers together. The 'DO NOT CONFUSE WITH' section names the exact alternatives and what distinguishes them, giving an agent clear when-to-use and when-not-to-use guidance.

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