Generate JSON Report

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate a non-destructive write operation. The description adds that it writes to disk and optionally records in a database, and returns a record with path. However, it does not disclose file overwrite behavior, naming conventions, or idempotency (e.g., whether calling twice overwrites or errors). This is a gap given the lack of idempotentHint annotation.

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?

Two sentences only: the first covers the action and optional sections, the second describes the return value. Every sentence is informative and there is no wasted text. Very concise and front-loaded with the core purpose.

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 the tool has 9 parameters (only 1 required) and no output schema, the description does well by listing the return fields (report_id, path, client_id, created_at). It also notes that db_path is optional. However, it does not mention that kundali must come from calculate_kundali (though schema says 'exactly as returned'), and it omits default values for output_dir and client_id (though present in schema). Overall, it covers the essentials for a complex tool.

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 100%, so each parameter is already described. The description adds further context by explaining that optional dasha, gochar, and panchang parameters 'adds the [section]', which clarifies their purpose beyond the schema. This enhances the semantic value beyond the schema alone.

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 uses a specific verb ('Assemble... and write') and names the resource ('structured astrology report draft as JSON'), clearly distinguishing it from siblings like generate_pdf_report (which produces PDF) and calculate_* tools (which only compute components). It also mentions optional sections, aligning with parameters.

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 description implies this tool is for generating JSON reports when the user wants programmatic access, while siblings like generate_pdf_report are for visual output. However, it does not explicitly state when to use this tool versus alternatives, nor does it specify prerequisites or exclusions (e.g., 'Use this if you need the report as JSON; use generate_pdf_report for a PDF'). The guidance is implicit and could be clearer.

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