Core: Call API

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

With no annotations, the description carries the full burden and does so well: it discloses the read-only GET semantics, that the signed receipt stores only a hash of path/query, per-call billing, authentication requirements (METRECEPT_API_KEY / Bearer), tenant scoping, and concrete error behavior (404 service_not_found, JSON {'error','status'} on vendor and prefix failures). This is substantial behavioral context beyond the schema.

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 core action and routing are front-loaded, and nearly every sentence contributes unique information (prerequisite, alternative, path constraint, billing, errors, auth). It is a dense single paragraph with multiple distinct concerns run together, which slightly reduces readability but wastes little text.

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 six parameters, no annotations, full schema coverage, and an output schema, the description provides everything an agent needs: prerequisites, auth model, tenant scoping, billing, path/query constraints, session grouping, and error responses. Return-value shape is appropriately left to the output schema.

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 100%, so the baseline is 3; the description adds meaningful semantics for path (must sit under allowed_path_prefix, with a concrete example), query (sent as the URL query string), and session_id (groups calls into one session receipt). It does not explain service_key beyond the schema, but the cross-parameter prefix constraint and session grouping add real value.

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 opens with a specific verb and resource ('Make a read-only GET call to a registered third-party API') and states the return ('vendor's response body, with a signed receipt'). It also explicitly distinguishes this tool from the sibling metrecept_fetch_web_pages, so an agent can route correctly without opening either schema.

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?

It gives explicit when-to-use ('authenticated vendor JSON APIs mid-session'), a prerequisite ('Register the service first with metrecept_register_api_service'), and an explicit when-not-to-use with the alternative named ('Not for public web pages: use metrecept_fetch_web_pages'). This fully covers the routing decision.

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