graded-x402

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

With no annotations, description notes auth requirement but does not disclose read-only nature or other behavioral traits. Minimal yet adequate for a simple retrieval tool.

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 with no fluff. Every word serves a 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?

Tool is simple with no params or output schema; description covers what it does and auth, but could mention if recent calls are limited or other specifics.

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?

Input schema has 0 parameters; description adds value by specifying the kind of data returned (balance, totals, calls). Baseline for 0 params is 4.

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?

Description mentions 'balance, totals, and recent calls', clearly indicating it retrieves account summary. Lacks an explicit verb like 'get' or 'retrieve', but the resource is well-specified.

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?

No guidance on when to use this tool versus siblings like 'create_account' or 'top_up_info'. The description only states the output and auth requirement.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the pricing model (USDC price, markup, minimum deduction) and requirement for account key. However, it does not disclose potential side effects, error states, or idempotency, which would be important for a costly operation.

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 description is two sentences, front-loaded with the core action, and each sentence adds essential information (action, pricing, requirements). No redundant or unnecessary words.

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 no output schema and three parameters, the description covers the pricing and requirement aspects but lacks details about return values, error handling, or what happens when credits are insufficient. This leaves the agent with incomplete context for robust usage.

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 input schema has 67% description coverage (2 of 3 parameters described). The description adds no parameter-specific detail beyond what the schema provides. It does not explain what the 'id' represents or how 'body' and 'query' affect the call, leaving a gap for parameter understanding.

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 clearly states the tool's purpose: 'Call a catalog service through the gateway.' It uses a specific verb ('Call') and resource ('catalog service'), and the context from sibling tools (e.g., 'get_service', 'list_services') further distinguishes it as an invocation action rather than a read operation.

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 when to use the tool ('to call a service') and specifies prerequisites ('Requires an account key with credits'). However, it does not explicitly mention when not to use it or provide direct comparisons with sibling tools like 'get_service' or 'list_services', but the context is sufficiently clear.

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

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

With no annotations, the description carries full burden. It discloses that the secret key is returned and shown only once, and that accounts start at 0 credits. This covers critical behavioral aspects (storage necessity, initial state) but omits details like idempotency or rate limits, which are acceptable for simplicity.

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 concise sentences front-load the purpose and critical information (key storage, credits). No redundancy or filler; every word 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?

For a zero-parameter creation tool with no output schema, the description covers all essential context: action, return value, storage warning, and starting state. It is fully complete.

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?

No parameters exist (0 params, 100% schema coverage). The baseline for 0 params is 4. The description adds meaning by explaining the tool's effect and return value, which is sufficient given no parameters to elaborate on.

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 clearly states 'Create a gateway account' with a specific verb and resource. It distinguishes from sibling tools like 'account' (which likely deals with existing accounts) by focusing on creation and mentioning the secret key and initial credits.

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?

While the description implies this is for initial account creation, it does not explicitly guide when to use it versus alternatives or provide conditions like 'use only once per account'. The mention of the key being shown once gives some contextual hint, but lacks direct usage direction.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions authorization requirements (Bearer token) and that credits land 1:1 within seconds, but does not discuss side effects, rate limits, or potential failures, leaving some gaps for a mutation tool.

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 description is two sentences, front-loaded with the purpose and key details (amounts, Stripe Checkout), followed by usage instructions and authorization requirement. Every sentence adds value with no wasted words.

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 low complexity (one parameter, no output schema), the description adequately covers what the tool does, how to use it, and what to do with the returned URL. It could be more precise about the return format (e.g., 'returns a URL'), but it is implied.

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% for the single 'pack' parameter, which already specifies it must be 5, 10, or 20. The description adds context that these are USD amounts for adding credits, but does not significantly expand beyond the schema. Baseline 3 is appropriate.

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 clearly states the tool creates a hosted card-payment link (Stripe Checkout) to add specific credit amounts ($5, $10, $20) to the user's account. It distinguishes itself from sibling tools like top_up_info (which likely provides info) and others by focusing on the creation of a payment link.

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 provides clear context for when to use the tool (to add credits via card payment) but does not explicitly state when not to use it or mention alternatives among siblings. It implies usage for card payments without discussing other funding methods.

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

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

With no annotations provided, the description must cover behavioral traits. It only states 'Free' (ambiguous) and lists returned fields. It does not disclose error handling, idempotency, or side effects, which is a significant gap for a read operation.

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 description is extremely concise with one sentence, front-loaded with the core purpose. Every word contributes value, listing specific return fields without redundancy.

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 simple nature (one parameter, no output schema), the description covers key return fields adequately. However, it lacks behavioral transparency and parameter semantics, which reduces completeness for an agent to use it correctly.

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 0%, so the description should compensate for parameter details. It mentions 'input schema' but adds no meaning to the 'id' parameter beyond what the schema provides. No format, examples, or constraints are given.

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 clearly states the tool returns full details for a single catalog service, listing specific fields like grade breakdown, prices, and input schema. The name 'get_service' aligns perfectly, and it distinguishes from the sibling 'list_services' which returns multiple services.

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 usage for retrieving full details of one service but does not explicitly provide when-to-use or when-not-to-use guidance. No alternatives or prerequisites are mentioned, though the context of siblings like list_services offers some implicit differentiation.

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

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

Discloses ranking criteria (demand, grade) and that it's free. No annotations provided, so description carries burden. Does not mention pagination behavior, rate limits, or output structure.

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?

Single sentence, no redundant words. Front-loaded with key information: action (search), scope (graded catalog), ranking, and cost.

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?

With 5 parameters, no output schema, and no annotations, the description covers scope, ranking, and cost well. Lacks details on output format or pagination, but adequate for a search tool with parameter descriptions in 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 baseline 3. Description adds context: catalog scope ('ours + the Bazaar'), ranking criteria ('real 30-day demand', 'agent-usability grade'), and cost ('Free'), which complements the schema definitions.

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 clearly states the tool searches a graded catalog of services, ranked by demand and usability grade, distinguishing it from siblings like 'get_service' (single service) and 'call_service' (invocation).

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?

Implied usage: search and list services. But no explicit guidance on when to use this vs. alternatives like get_service or call_service. No exclusion criteria provided.

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

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

No annotations provided, so description should disclose behavior. It does not mention whether it is read-only, requires authentication, or its effect. Fails to add value beyond minimal hint.

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?

Single sentence, concise but lacks structure. Could be front-loaded, but not clearly organized. Adequate length but minimal information.

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 no annotations or output schema, description is incomplete. Does not explain what the tool actually does (e.g., returns text, list, or link). Missing behavioral and output details.

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?

No parameters, schema coverage trivial. Baseline 4 for 0 parameters. Description adds context about two methods, but not about parameter absence. Adequate.

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?

Description says 'How to add credits' which suggests instructional purpose, but tool name 'top_up_info' implies informational. It does not clearly state what the tool returns or does. Vague purpose with no concrete 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?

No explicit guidance on when to use this tool. References create_topup_link as alternative for card checkout, but does not differentiate from other siblings like account or create_account.

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