The Bot Forum

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes beyond annotations by disclosing that the tool charges nothing, that the data key returns 403 wrong_credential, and that a missing string returns 401 invalid_key. These operational behaviors are valuable context an agent cannot infer from annotations alone.

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 dense but every clause earns its place: the returned fields are listed first, then credential requirements, then error behavior and cost. It is a single well-structured paragraph with no filler and no redundancy with the schema.

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 read-only single-parameter tool with a full output schema, the description covers the input provenance, authentication constraints, expected error responses, and cost implications. Nothing an agent needs to call it correctly is missing.

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 the input schema fully documents the 'secret' parameter, including its origin and precedence. The description reinforces this by repeating that the secret must come from sign_up and that the data key cannot be used, but it does not add significant new meaning beyond the schema's already detailed parameter description. 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 opens with a specific verb and resource: 'Reads the account behind the secret,' and enumerates exactly what the tool returns (tier, Terms version, products, credit balance, usage history, balance movements). This clearly distinguishes it from sibling tools like get_product or list_products, which focus on catalog data rather than account status.

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 gives clear context on how to invoke the tool: pass the secret returned by sign_up, not the client configuration's data key. It even explains the failure modes for using the wrong credential. It does not explicitly name alternative sibling tools or state when not to use them, but the authentication guidance is strong enough to guide correct use.

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?

Goes well beyond the annotations by disclosing billing behavior (success billed, refusal free), response contents (payload, meta block, cost headers), and the exact refusal/error envelope with 402 handling. This is rich behavioral context that annotations alone do not provide.

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 endpoint are front-loaded, and the remaining sentences each add necessary operational detail (auth, cost, errors). It is fairly long but information-dense with 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 four-parameter data-fetch tool, the description covers endpoint construction, authentication, routing to get_product, billing, response shape, and error handling. The output schema exists and the description names the return fields, so an agent has enough to invoke 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 covers 100% of parameters, so the baseline is 3; the description adds meaningful extras: auth precedence (argument wins over header), the 'never the secret' warning, and that params are passed through as query parameters. This is useful beyond the schema's property descriptions.

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 a specific action ('Fetches one data response') with the exact HTTP GET endpoint shape and route semantics, and names sibling tools (get_product, get_topup_link) for supporting operations. The scope is unambiguous and distinct from list_products/get_product.

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 clear operational context: use data_key only when Authorization header cannot be sent, consult get_product for route params, and use get_topup_link after 402. It does not explicitly state 'when not to use fetch_data', but the alternative references cover the main routing decisions.

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?

Annotations already mark the tool read-only, idempotent, and non-destructive. The description adds non-obvious context: no API key is needed, it charges nothing, data comes from the platform's published product record, and an unknown slug returns the catalogue's served slugs. There is no contradiction with the annotations.

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?

Three sentences, with the core return value front-loaded, followed by usage guidance and an edge case. Every clause adds value: content, routing, auth/cost, or error behavior. No fluff or repetition.

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 single-parameter read-only tool with an output schema and strong annotations, the description covers output content, its relationship to fetch_data, error behavior, and authentication/cost. Nothing an agent needs to invoke it correctly is missing.

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 documents the only parameter product at 100% coverage, including its pattern and source ('a product slug from list_products'). The description reinforces that the parameter is a slug and adds unknown-slug behavior, but it does not significantly extend the schema's parameter semantics.

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: 'Returns one product by slug' and enumerates the contained catalogue fields (price, licence, lifecycle state, specification address) plus route data for fetch_data. This clearly differentiates it from list_products and fetch_data.

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 explicitly instructs 'Use it before fetch_data' and explains that route names come from this tool. It also describes the unknown-slug fallback. It does not explicitly name list_products as an alternative, but the 'one product by slug' scope and the input schema's reference to list_products make the selection context 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?

Beyond the annotations, the description discloses that the tool only opens a top-up and does not execute payment, that card details never reach the Forum, that the returned hosted_url is short-lived, that repeat calls while a page is open return the same page, and that credits appear in account_status upon completion. This is exactly the behavioral context an agent needs.

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 compact and front-loaded: the core action and the most important caveat ('no tool pays') come first, and each subsequent sentence adds a distinct, necessary fact. There is no filler or redundant framing.

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 output schema and annotations, the description covers all essential operational context: authentication via the secret, currency and amount constraints, idempotent behavior, the external payment page, and the post-payment effect on account_status. An agent has everything needed to invoke the tool 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 coverage is 100%, and the schema already documents the cent-based amount, the $10 minimum, USD-only acceptance, and the secret-vs-data-key restriction. The description reinforces these details but adds little beyond what the parameter descriptions already provide, so it stays at the baseline for high schema coverage.

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 states a specific action — 'Opens a top-up for the account and returns the payment intent with hosted_url' — and clearly distinguishes this from paying, noting that no tool pays and a human completes payment on the provider page. This makes it easy to tell get_topup_link apart from sign_up and account_status.

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 gives strong usage context: pass the secret returned by sign_up, never the data key, and understand that repeated calls while a page is open return the same page. It stops short of explicitly naming sibling alternatives and saying 'use X instead of Y,' but the when-not guidance is clear enough.

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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations: no authentication key needed, no cost, and the price semantics including the credit conversion and charged-price guarantee.

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?

Three sentences, each earning its place: the main scope and output fields, the auth/cost caveat, and the routing to get_product. Front-loaded and free of 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?

The description is complete for a zero-parameter, read-only tool. It covers what is returned, the access and cost profile, and the natural next step; an output schema handles the detailed return shape.

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 tool takes zero parameters and schema coverage is 100%, so parameter semantics are effectively moot. The baseline of 4 applies because there are no parameters to clarify.

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 a specific verb and resource: 'Lists every data product the Forum serves', and enumerates the exact fields returned. The phrase 'platform's own catalogue answer' clearly distinguishes it from get_product and other siblings.

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?

Clear context is provided: it is the catalogue tool, requires no key, and charges nothing. It also directs the agent to call get_product next for routes and parameters, though it does not explicitly say when not to use list_products.

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 annotations carrying essentially no safety profile, the description carries the full behavioral burden. It discloses that the secret and first data key are shown exactly once, that the account gets a 1,000-credit grant, that duplicate addresses return 409 email_exists with next_action login_to_link, and how the configure block relates to future fetch_data calls. This is rich, non-obvious behavioral context.

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 dense but every sentence earns its place: creation + returns, configure-block usage, secret usage, and duplicate-account behavior. Critical one-time-display warnings are front-loaded in the first sentence, and no filler or repetition exists.

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?

Even though an output schema exists, the description adds crucial integration context: how to use the configure block, where to pass the secret, and how to handle the duplicate-account error. Nothing needed to call and consume sign_up correctly appears to be missing.

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 reinforces that email is the account identity and that one account exists per address, which echoes the schema rather than adding new parameter syntax or formatting details beyond it.

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 uses a specific verb and resource: 'Creates a Forum account for an email address.' It clearly differentiates sign_up from siblings like account_status and fetch_data by framing it as the account-creation entry point, and it specifies the account identity and the signup grant.

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 gives clear post-signup usage guidance: pass data_key.key to fetch_data until reconnect, pass secret to account_status and get_topup_link, and handle 409 with next_action login_to_link. It does not explicitly state 'use this instead of X when no account exists,' but the sibling routing is strongly implied through these instructions.

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