IMBA Agent Docs

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds useful behavioral context beyond those annotations by stating the tool 'Does not move money' and instructing the agent to 'Cite as-is', which clarifies both its safety profile and how its output should be consumed. No contradiction with 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?

The description is compact and front-loaded with the core purpose, followed by a tight list of covered topics and two short sentences that add real value. Every sentence earns its place, with no redundant 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 zero-parameter, read-only facts lookup, the description is complete: it states what the tool covers, how the output should be used, and confirms it is non-financial and safe. With no input parameters and no output schema, nothing essential is missing for an agent 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?

The tool has zero parameters and the schema description coverage is 100%, so there are no parameter semantics for the description to clarify. Per the baseline for zero-parameter tools, a score of 4 is appropriate; the description reasonably focuses on the content returned rather than inputs.

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 identifies the resource as a canonical prepaid-agent policy and catalog and enumerates the exact topics covered. It lacks a direct verb like 'retrieves' or 'returns', and it does not explicitly differentiate itself from siblings such as get_tier_policy or get_catalog_placement, but the content scope is otherwise unambiguous.

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?

'Cite as-is' gives the agent a clear instruction on how to use the returned content, and 'Does not move money' signals that this is a safe reference lookup rather than an action tool. It provides clear context but does not explicitly state when to prefer this tool over its siblings or list exclusions.

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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond that: 'Does not move money' clarifies safety, and 'Cite as-is' plus 'MCP tools per job' suggest how the output should be used.

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 very short and information-dense, with the core content front-loaded in a compact list. The phrasing is somewhat telegraphic ('Cite as-is'), but every clause adds useful information and there is 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 zero-parameter, read-only informational tool with no output schema, the description reasonably covers what the tool offers, how the output should be treated, and a key safety caveat. It could be slightly more explicit about the return format, but the title and description together are adequate for this simple tool.

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 has zero parameters and 100% schema description coverage, so the baseline is 4. There are no parameter semantics the description needs to explain; it correctly focuses on the tool's content and behavior instead.

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 identifies the resource as a playbook of agent use cases ('Visas prepaid, travel eSIM, gift cards, KYT address screen') and the title confirms 'What agents can buy.' It lacks an explicit verb such as 'returns' or 'lists,' but the resource and scope are clear and specific.

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 no guidance on when to use this tool versus sibling tools like get_agent_facts or get_catalog_placement. It implies this tool is the playbook source, but it never states conditions, exclusions, or alternatives, leaving the agent to infer when to call it.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds an example of the kind of output (which directory belongs to which MCP) but does not discuss return format, limits, or any edge cases. It adds minimal context beyond 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?

The description is a single, compact sentence with the key info front-loaded. It wastes no words and is immediately scannable.

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, read-only lookup tool with no output schema, the description covers the essential information: what mapping it returns and an example. It could mention the form of the result (e.g., a list or map), but that is not critical for a simple query. The description is sufficiently 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?

The tool has zero parameters, so the schema is empty. Baseline for 0 parameters is 4; the description does not need to explain any parameter semantics, and it doesn't reduce the score. No extra value is needed for this dimension.

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 what the tool reports: which directories take the docs MCP vs the spend MCP, and gives a concrete example ('OpenAI is docs-only'). It is distinct from sibling tools like get_public_url or list_docs_urls, so an agent can immediately tell which to use.

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 (checking placement for catalogs) but does not explicitly state when to prefer this over alternatives or list exclusions. Sibling names hint at different purposes, but no comparative guidance is given, leaving some inference required.

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 read-only, idempotent, and non-destructive behavior; the description adds the HTTP method, the allowlist restriction, and an explicit side-effect guarantee ('Never calls register/deposit/buy'). This is useful behavioral context beyond the structured annotations, though error and rate-limit behavior is not covered.

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 short sentences front-load the core behavior and then add a valuable negative guarantee. There is no filler or 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 simple one-parameter, read-only fetch with rich schema coverage and annotations, the description is nearly complete. Minor gaps are the absence of an explicit pointer to list_docs_urls for obtaining allowlisted URLs and no mention of the returned payload shape, but neither blocks correct invocation.

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 single url parameter at 100% coverage, and the description's mention of doc categories largely mirrors the schema. No additional parameter semantics are added, so the baseline of 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 uses a specific verb/resource pair ('HTTP GET of an allowlisted public docs URL') and enumerates the allowed doc categories, making the tool's scope unambiguous. This distinguishes it from sibling getters, which target specific fact sets, and from transaction tools via 'Never calls register/deposit/buy.'

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 the tool is for fetching any allowlisted public docs URL, and the schema reinforces the allowable URL set. However, it doesn't explicitly state when to prefer this over sibling tools such as get_agent_facts or list_docs_urls, nor does it mention using list_docs_urls to discover valid URLs.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds policy rules but no observable tool behavior such as how results are formatted, whether it can return empty/failure states, or how the policy maps to agent actions. It does not contradict the annotations, but it also does not enrich operational transparency.

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 very short, with no filler words, but the first clause 'Tier 0 vs 1+' is a fragment and the rest assumes domain knowledge (AML, Convert, Withdraw). It is not merely concise but under-specified for a general agent audience.

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 tool with no parameters and no output schema, the description is the only explanatory surface, and it leaves key terms undefined and no expectation of what the returned policy object looks like. An agent may know this is about tier policy, but it cannot confidently interpret 'Convert at 1 is a separate request' without additional domain context.

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 zero parameters and 100% schema description coverage, so there are no parameter semantics to explain. Baseline for a zero-parameter tool is 4, and the description does not need to compensate for any missing parameter documentation.

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 conveys domain content ('Tier 0 vs 1+', 'Convert closed at 0 (AML)') that aligns with the tool name and title, so an agent can infer this is a lookup of tier policy criteria. However, it never explicitly states a verb like 'returns' or 'provides', and the policy language is cryptic ('Convert', 'Withdraw' are not defined as operations or outcomes). It distinguishes itself from siblings by topic but not by explicit comparison.

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?

There is no guidance on when to invoke this tool versus alternatives such as get_agent_facts or get_catalog_placement. The description only states policy facts; it does not say 'use this when you need...' or mention any exclusions. An agent must infer applicability from the name and terse content.

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 establish readOnly, idempotent, and non-destructive behavior, and the description adds no conflicting claims. It adds a little context by implying the returned URLs are organized around the listed documentation topics, but it does not describe output format, cardinality, or pagination.

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 very short and contains no filler, but it is a telegraphic list rather than a structured sentence. It is not misleading, yet it lacks a clear subject-verb framing that would make it front-loaded.

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 no-parameter read-only list tool, the description is nearly sufficient, but without an output schema it should say what the tool returns (e.g., a list of URLs grouped by the listed topics). The categorized fragment hints at the content but does not fully specify the response.

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?

With zero parameters, there is no semantic burden on the description; the baseline of 4 applies. The description adds nothing about parameters, but none exist 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?

The description is a fragment ('HowTo, use cases, tiers, discovery, OpenAPI, MCP endpoints') and does not state a verb or resource; only the title 'List public Agent URLs' makes the purpose clear. It hints at the content categories but does not explicitly distinguish this list tool from get_public_url.

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?

There is no guidance on when to call this tool instead of siblings such as get_agent_use_cases, get_public_url, or get_tier_policy. The categories might imply a directory use case, but that is not stated.

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