Agentropolis

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

Goes well beyond the annotations: states Agentropolis holds no keys or funds, never changes payTo/amount, charges no fee, yet warns 'real money can move' because a signed payment is forwarded and may be settled. Adds concrete limits (https host only, 256 KB request, 2 MB response, 25 s timeout, 20 calls/min) that annotations cannot convey.

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?

Longer than typical but front-loaded and organized into purpose, gating condition, flow, limits, and example. Given the multi-step payment protocol and 8 parameters, the length is largely justified, though the limits and example could be trimmed slightly.

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 high-complexity, non-idempotent, open-world relay tool with no output schema, the description closes the key gaps: it describes the returned payload (status, headers, body), the full auth/payment sequence, and hard limits. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds protocol-level semantics the schema lacks: the first call is made without payment to elicit the 402, and payment_signature (x402 v2) vs x_payment (v1) are the second-call credentials. The worked example also anchors id/endpoint/method/body usage.

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 ('Send a request to a listing's x402 endpoint ... get the seller's raw response back') and immediately scopes it against siblings by requiring buy='relay_x402' and routing other listings to get_kit_manifest. An agent can distinguish it from get_kit/get_kit_manifest without opening a 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?

Explicit when-to-use ('only for listings whose search result has buy="relay_x402"') and when-not ('for any other listing, call the seller directly using get_kit_manifest'), naming the alternative tool. The two-step 402 flow and payment prerequisites are spelled out rather than left to inference.

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 readOnlyHint annotation: it discloses that Agentropolis makes no request to Coinbase, does not cache or republish Bazaar data, and that the tool only returns a link the user must open themselves. These are material behavioral facts an agent could not infer from the schema or 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?

Front-loaded with the purpose and then the when-to-use condition, with no wasted preamble. 'Read-only' is mildly redundant with readOnlyHint=true, and the parentheticals add length, but each sentence carries useful 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?

An output schema exists, so return values need no elaboration, and the description still notes the return is a link. For a single-parameter, side-effect-free tool, nothing needed for correct invocation 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 coverage is 100% so the baseline is 3, but the description adds a concrete invocation example ({'q':'web search'}) that shows the argument shape in practice. It does not restate the maxLength or omit-for-home-page rule, which the schema already covers.

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 ('Build a URL that searches Coinbase's x402 Bazaar'), and clarifies it produces a link rather than performing a search. It also implicitly differentiates from siblings like search_kits by naming the Agentropolis index as the contrasting source.

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 says when to use it ('when you want x402 services that may be missing from the Agentropolis index') and what the result is for ('for you or your user to open'). It lacks an explicit when-not or a named alternative sibling, but the condition is clear enough to route correctly.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuine non-obvious behavior: an anonymous detail view is logged for seller analytics, and unknown ids return an error result with error 'not_found'. Those are traits the annotations cannot express, though it stops short of describing the response payload 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?

Front-loaded with the core purpose, then usage guidance and routing. Every sentence carries load — returns, routing, side effect, error behavior, example. Slightly dense but 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?

Output schema is declared, so return-value structure need not be repeated; the description instead covers the behavioral edges an agent needs: read-only/no-auth, analytics side effect, not_found semantics, and sibling routing. Complete for a single-param read 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?

Schema description coverage is 100%, so baseline is 3. The description goes beyond the schema by stating that unknown ids produce a 'not_found' error result and by supplying a concrete example id, which helps an agent construct valid calls rather than just understand the type.

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 ('Get the full Agentropolis record for one listing by id') and enumerates the returns (summary, pricing, trust evidence, badge tiers, sources, links). It also explicitly names the sibling it is not — get_kit_manifest — so an agent can route between the two 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?

Gives an explicit workflow trigger ('Use it after search_kits to judge whether a listing is worth using') and an explicit exclusion with the alternative ('use get_kit_manifest instead when you need the machine-readable invoke contract'). Both the when and the when-not are covered.

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, non-destructive and closed-world, so the safety profile is covered; the description still adds value by stating 'no auth' and, more importantly, the provenance caveat that seeded listings are generated from public metadata and may be incomplete, with a pointer to the seller's live 402 challenge for exact prices. It stops short of rate limits or error behavior, but the data-reliability warning is a meaningful disclosure 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 purpose and contents are front-loaded, then usage routing, then the provenance caveat, then an example. Every sentence carries information, though the enumeration of manifest fields and the trailing example add mild length for a one-parameter read.

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?

An output schema exists, so return values need not be explained, and the description covers purpose, alternatives, auth, and a reliability caveat for seeded listings. The only minor gap is the absence of any guidance on failure modes (e.g., unknown or malformed listing id), which for a single-required-param lookup would be the last useful addition.

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% and the single 'id' parameter is fully documented with format guidance and examples. The description's example ({'id':'seenly.seenly-pitch-kit'}) merely restates what the schema already conveys, so baseline 3 applies.

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 ('Get the kit.json v0.1 manifest for one listing') and enumerates the payload contents (endpoints, schema refs, payment offers, discovery files, trust summary). It explicitly differentiates itself from the sibling tools get_kit and call_kit, so an agent can route 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?

Gives an explicit when-to-use ('when you are about to call a listing yourself') and names two alternatives with their selecting conditions: get_kit for human-readable details and trust evidence, call_kit for invoking an x402 listing. No 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 cover the safety profile (read-only, idempotent, non-destructive), yet the description adds genuinely non-obvious behavioral context: wash signals are filtered out of the numbers, buyer counts are summed per service so a multi-service wallet is counted repeatedly, and the data is CC BY 4.0 requiring attribution. These are interpretive caveats an agent could not derive from the annotations or empty 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?

Front-loaded with purpose and intended use, and most sentences carry distinct information (provenance, licensing, aggregation quirk, cross-references). It is a dense single block, and 'Read-only, no parameters' partially restates the annotations and schema, so it is efficient but not flawless.

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?

An output schema exists, so return values need no explanation. The description supplies everything else an agent needs: what is measured, what is excluded, the source and its license, an important counting caveat, and pointers to equivalent artifacts (/stats, /reports).

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, so per the rubric the baseline is 4. The description reinforces this ('Read-only, no parameters'), which is consistent with the empty schema but adds no further parameter detail to give.

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 (get 30-day x402 paid-usage statistics per category) and adds a scope qualifier (wash trading filtered out) that defines the dataset precisely. It also explicitly contrasts itself with search_kits for individual tools, so an agent can distinguish it from siblings without opening any 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?

Gives concrete intended uses ('market sizing or price benchmarking') and names the alternative tool plus the condition that selects it ('to find individual tools use search_kits'). No inference is required to pick between this and its siblings.

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 the safe-read profile, yet the description adds real operational context: stub endpoints return HTTP 501, payments_enabled currently reflects whether the platform charges (false today), and the status taxonomy. This is behavior an agent cannot get from the annotations or an empty parameter 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?

Front-loads the purpose and the status vocabulary before the usage guidance, and every sentence carries information. The mid-sentence enumeration of covered areas (badges, x402 relay, billing) is slightly list-heavy but earns its place as feature coverage.

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?

An output schema exists, so return values need no explanation, and the description supplies the remaining context an agent needs: it's parameterless, read-only, non-listing, and how to interpret stub states and payments_enabled.

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?

Zero parameters, so the 4 baseline applies. The description reinforces this with 'Read-only, no parameters,' which is a useful confirmation despite adding no new semantics beyond the empty schema.

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 (list) and resource (Agentropolis platform features) with the enumerated status vocabulary (live, partial, stub, planned), and explicitly bounds the scope: 'it describes Agentropolis itself, not listings.' This distinguishes it cleanly from siblings like get_market_snapshot, list_categories, or search_kits.

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 an explicit trigger ('check whether a platform capability exists before relying on it') and an explicit exclusion ('describes Agentropolis itself, not listings'), which is exactly the disambiguation an agent needs against the listing/market siblings. No 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, closed world), and the description's 'Read-only, no parameters' largely restates them. However, it adds real behavioral substance by enumerating what the explanation covers — payment evidence rules, wash-trading exclusions, low-sample caps, exclusion of the operator's own test purchases, and null-score semantics — which sets accurate expectations for the content returned.

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?

Front-loaded with purpose, then the usage clause, then the disambiguation, then the read-only note. The opening sentence is a dense run-on carrying a long list of covered topics, but every clause earns its place and nothing is padded.

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 an output schema present, the description needn't describe return values, and it doesn't. For a zero-parameter, read-only explainer whose annotations cover safety, the description supplies everything needed: what it explains, what it is not, and how to consume the result alongside sibling tools.

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?

Zero parameters, so the baseline is 4 per the rubric. The description correctly reinforces 'no parameters,' and the empty schema is fully consistent with that, leaving nothing ambiguous to specify.

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 (explain) and resource (how trust scores are computed and results ranked), names the method version hub-trust-v0.1, and explicitly distinguishes itself from get_kit/search_kits by declaring it returns the method, not any listing's score. An agent can separate it from every sibling without opening a 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?

Explicitly says when to use it: to interpret the trust and badge fields coming out of search_kits or get_kit. It also states the exclusion ('not any listing's score'), which prevents misuse as a lookup for a specific kit's score.

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, but the description adds ordering ('largest first'), the approximate cardinality (~18) and the id format (snake_case), which help the agent shape expectations. It stops short of describing pagination or exact return shape, though the output schema covers that.

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?

Front-loaded with the core operation, then usage, then a pointer to a sibling and a human-facing URL. Dense and largely efficient, though the trailing '/categories' URL adds little for an agent caller.

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 an output schema present, the description needn't explain return values, and it doesn't. It covers purpose, sorted order, cardinality, and sibling routing; a minor gap is it never states whether the result is truncated or 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?

Zero parameters, so baseline is 4. The description reinforces this with 'no parameters' and spends its space instead on the values the caller will receive, which is exactly the right emphasis for a parameterless tool.

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+resource (list every category in the Agentropolis index) plus the key output attribute (listing count, sorted largest first). It also gives concrete examples of the category ids, so an agent knows exactly what it gets back without opening the 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?

Explicitly names two use cases (valid values for search_kits' category filter, seeing index coverage) and routes the agent elsewhere for a different need (get_market_snapshot for paid-usage numbers). Alternatives and conditions are stated, not implied.

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, closed-world and non-destructive, so the safety profile is covered. The description adds substantive context beyond that: that it surfaces licensing/terms decisions and robots handling, and that it takes no parameters. It stops short of describing pagination or result ordering, but for a static reference listing that is a minor omission.

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?

Front-loaded with the resource and scope, followed by a purpose clause and an explicit boundary against search_kits. The parenthetical examples (Official MCP Registry CC0, Coinbase Bazaar link-out only) are dense but concretely clarify the shape of the license decisions, so they earn their space.

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?

An output schema exists, so return-value documentation is not required, yet the description still signals what kinds of facts each entry carries. With annotations covering the safety profile and usage/exclusions covered in prose, an agent has everything needed to call this 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 takes zero parameters, which is the baseline-4 case. The description reinforces this with 'no parameters,' so there is no ambiguity for the caller, though there is nothing further to specify semantically.

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?

Names a specific verb (List) and concrete resource (registries/directories ingested or excluded), plus the per-source detail returned (license/terms decision, robots handling, listing count). It explicitly separates itself from the sibling search tool, 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?

States the positive use case ('check provenance or the attribution required before citing results') and the exclusion ('it does not search listings (use search_kits)'), naming the alternative tool. Nothing about when to reach for it is left to inference.

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 (readOnly/idempotent/non-destructive), it discloses no-auth, never-pays, anonymous query logging, BM25 ranking boosted by payment-verified trust and Live-Tested badges, the meaning of trust.score null, the results/featured/sponsored array structure, and that listed prices are hints while the seller's 402 challenge is authoritative. This is unusually rich 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?

Front-loaded with the purpose and routing guidance, and nearly every sentence carries non-redundant information (safety, ranking, result-array shape, price caveat, logging, example). It is on the long side and the featured/sponsored sentence is somewhat dense, but the length is justified by the number of behaviors disclosed.

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 discovery endpoint, the description covers query intent, filters, ranking, result partitions, trust semantics, price caveats and privacy logging. An output schema exists, yet the description still gives the agent enough to interpret and act on results without gaps.

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 baseline is 3; the description still adds meaning beyond the schema, e.g. that trust.score null means no payment evidence (not negative) and that listed prices are hints vs the live HTTP 402 challenge, plus a worked query example.

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 (Search) and resource (the Agentropolis index of 48,190 agent-usable listings), enumerating what is indexed (MCP servers, x402/MPP APIs, A2A agents, kits). It explicitly differentiates itself from siblings like get_kit, get_kit_manifest, list_categories and get_market_snapshot.

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 explicit ordering guidance ('Use it first when you need a tool for a task; then use get_kit ... or get_kit_manifest') and names when-not-to-use it ('Not for browsing categories (list_categories) or market totals (get_market_snapshot)'). Alternatives and their selecting conditions are spelled out.

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