gov_query

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

With no annotations provided, the description carries the full disclosure burden, but it only adds a cost figure and doesn't state whether calls are read-only, require special permissions, or have any side effects. It also omits rate-limit or error behavior, so the agent has incomplete behavioral expectations.

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 tight sentences: first states purpose with examples, second gives discovery instruction and cost. No filler, all information is action-relevant.

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?

The description tells the agent how to find services and parameters and how much it costs, but it never describes the response format or any failure modes, which is significant because there is no output schema. The pointer to gov_list_services compensates for parameter discovery but not for return-value expectations.

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?

The schema already covers both parameters (service and params), and the description adds the crucial guidance that valid service IDs are discoverable via gov_list_services and gives two examples. This goes beyond the schema's static property descriptions, helping the agent populate the params object meaningfully.

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?

Clearly states it can call any of SuVerse's 128 US-government data/search services by ID, with concrete examples ('sec.company_info', 'nps.parks'). This distinguishes it from sibling tools that target specific agencies; it's the generic invocation endpoint.

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?

Explicitly instructs to use gov_list_services to discover service IDs and their parameters, which tells the agent how to find the necessary inputs. It also states the per-call cost, helping with cost-conscious selection, though it doesn't mention dedicated siblings as alternatives.

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