Generate Kundli Matching Report (PDF or HTML)

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

Annotations only declare readOnly=false, destructive=false, idempotent=false, openWorld=true; the description adds substantive behaviour beyond that: pdf is stored and returns a url while html/markdown are returned inline and not stored, price is identical across formats, and the output is non-AI generated. The 5,000-credit Tier 7 cost and the confirm-first instruction are meaningful operational disclosures. It still says nothing about latency, async behaviour, or failure modes on invalid birth data.

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?

Front-loads the deliverable and format before the section inventory, and the final sentences about partner roles and coordinate requirements are well placed. The middle sentence is a long comma-chained list of report sections, but each item genuinely describes output content rather than padding.

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?

For a 9-parameter premium report tool with an output schema, the definition covers what the document contains, the three output formats and their differing storage behaviour, partner ordering, the coordinate requirement, the no-AI nature, and the cost gate. Remaining styling and window parameters are documented in the schema, so nothing critical for correct invocation is missing.

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 78%, so the schema already carries most parameter meaning, including the groom/bride role of chart1/chart2. The description reinforces that chart1 is the groom and chart2 the bride and that coordinates are required for both, but adds little that the nested schema descriptions do not already state, and the remaining parameters (years, fromDate, school, mangalSchool, language, whitelabel) are left entirely to the schema.

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?

States a specific verb+resource (renders the /vedic/compatibility/couple-report reading as an A4 PDF, HTML or Markdown) and enumerates exactly what the document contains (Guna Milan out of 36, eight kootas, ten Porutham factors, Mangal/Nadi/Bhakoot doshas, navamsa, Vimshottari periods). This clearly separates it from the sibling data endpoints and the other report tools.

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?

Gives clear operating context: which route's reading it renders, that coordinates are mandatory for both partners, and an explicit premium-cost warning telling the agent to confirm with the user (~50% of free monthly budget) before invoking. It does not explicitly name a when-not or a named alternative among the many sibling report tools, which keeps it below a 5.

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