API Compute (POST)

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, and the description reinforces them ('stateless compute', 'allowlisted paths only') without contradicting. It adds non-schema behavior an agent would otherwise miss: billing semantics ('4xx/5xx are refunded') and the compact-output meaning of format 'llm'. Lacks detail on auth and rate limits, so not a 5.

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 triggering condition is front-loaded in the first clause, and the sentences are dense with actionable facts (return shape, statelessness, API target, allowlist, refund rule). Slightly compressed/telegraphic phrasing ('4xx/5xx are refunded') costs a little readability but there is no filler.

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 7-parameter pass-through with nested free-form body/query objects and no output schema, the description covers routing, return type, and error billing but says nothing about what the body should contain or how to construct valid payloads. Adequate to select and fire the tool, thin on how to succeed with it.

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 57%, so the schema does most of the work. The description adds real value for one parameter by explaining that format 'llm' means compact output, and ties 'path' to find_calculation, but leaves body, query, preset, and legacy output_mode unexplained despite arbitrary nested objects being the hardest part of the call.

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 the verb (POST compute) and resource (allowlisted endpoints on the Open Ephemeris REST API) and names the triggering tool (find_calculation returning a POST path). It clearly separates itself from dev_read_api for GET paths. It stops short of 5 because the actual operation is a generic pass-through, so the value is mostly in the routing rule rather than a domain-specific action.

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 an explicit trigger ('when find_calculation returns a POST path'), example cases (KP, Varshaphal, Chinese calendar, bounds, eclipses), and the routing exclusion ('GET paths go to dev_read_api'). An agent knows exactly when to pick this tool over its closest sibling without opening any schema.

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