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

Beyond what annotations already provide (readOnlyHint, openWorldHint), the description discloses the data limitations (metadata only, no full text, no case titles), the output cap (up to 3 records), and crucial operational details: cost ($0.002 USDC per successful call), payment rails (x402 on Base, Solana, Arc), and the fact that failed calls are not charged. That is a lot of actionable behavioral context an agent needs before calling.

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 definition is front-loaded with the resource and return payload, then layers on limitations and pricing in a tight, information-dense sentence. No fluff, though the long pricing clause is packed rather densely; splitting it slightly would read better, but every clause earns its place.

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, return-field details need not be explained, yet the description still summarizes them consistently. It covers data scope, limitations, parameter behavior, and cost/billing — everything an agent needs to decide and correctly invoke a paid, metadata-only call.

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 both parameters (year, limit) are already documented with ranges and defaults, and the description corroborates them (year, up to 3 records) without adding new syntax or format detail. This is the baseline case where the schema does the heavy lifting.

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 is specific: it names the source (AWS Open Data, CC-BY-4.0), the resource (Indian Supreme Court judgments) and exactly what is returned (judgment IDs, neutral citation, scrape date for up to 3 records). It also constrains what it is NOT (metadata only, no full text, no case titles). It does not explicitly name a sibling like gov_caselaw_access or gov_justia_case_law to point the agent away, so the differentiation is implicit rather than stated.

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?

Use is implied — 'for a judgment year' suggests the year-based query — but there is no explicit when-to-use, when-not-to-use, or alternative routing. Given many sibling court/caselaw tools exist, an explicit pointer (e.g., 'use gov_caselaw_access for full text') would help. The metadata-only caveat is the closest thing to a routing hint.

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