Dietary Suggestions

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely useful operational context — a POST endpoint, the four required inputs, and a 10-credit Tier 1 cost — but says nothing about how the element is computed or what the result contains.

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 core sentence is front-loaded and carries no filler. The bracketed metadata lines are boilerplate but compact and each adds a fact (group, endpoint, required inputs, cost), so nothing is wasted.

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 needn't be described, and cost/endpoint/required inputs are covered. But for a 13-parameter personalized chart computation with 23% schema coverage, the definition leaves the agent guessing what astronomical inputs actually drive the dietary output.

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 but barely does: it restates the four required fields and ignores city, name, cosmogram, zodiacType, houseSystem, and ayanamsaId entirely. No guidance on whether timezone vs. timezoneOffset should be supplied or what the birth-data fields mean in this context.

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?

"Element-based dietary focus: emphasize/avoid foods + cooking style" states a specific output (foods to favor/avoid plus preparation style) derived from astrological element. It is clearly distinct from siblings like astroway_pet_diet_by_sign or astroway_wellness_herbs, though it never says whose element (natal vs. transit) is being read.

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?

No when-to-use, when-not-to-use, or alternative is named. Nothing tells the agent whether this is a personalized natal recommendation or a date-based daily one, nor how it relates to astroway_wellness_medical_astrology or astroway_wellness_herbs.

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