Blackhull agent-economy intelligence

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

With no annotations provided, the description usefully discloses that disputes are free, are rechecked from fresh data on the next daily run, result in upheld/withdrawn outcomes, and are publicly visible at /disputes. It still omits auth requirements, rate limits, or whether a dispute can be edited/withdrawn by the submitter, so it is not fully exhaustive.

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 short sentences, front-loaded with the action and resource. "Free" and the recheck/outcome lifecycle are packed efficiently 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?

The description covers the dispute lifecycle and public-outcome behavior well, but with no annotations, no output schema, and 0% schema description coverage, it should also explain the required `url` and `code` parameters. As written, an agent understands the purpose but lacks enough parameter detail to invoke it confidently.

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?

All three parameters have 0% schema description coverage, and the description does not explain any of them. It does not clarify what `url` should point to (report URL vs. finding URL), what `code` identifies, or what the `reason` enum values mean, leaving required-parameter semantics entirely undocumented.

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, "Dispute," and identifies the exact resource: a finding in one of Blackhull's x402 service reports. It is immediately distinguishable from all listed sibling tools, which serve unrelated discovery/request functions.

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 phrase "Dispute a finding" implies the usage context, and the description adds outcome details (recheck, uphold/withdraw, public outcomes). However, it does not explicitly state the qualifying condition for filing a dispute or name any alternatives or 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?

With no annotations, the description carries the full burden, and it does disclose the temporal window (this week) and the ranking metric (star deltas) plus that servers are 'newly seen'. It says nothing about ordering, whether results are cached/refreshed, or auth requirements, which are gaps for an unannotated 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?

One sentence with no waste, and the primary content (this week's fastest movers) is front-loaded. It is arguably too terse rather than too long.

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 no output schema and no annotations, the description should describe the shape of the return (two lists? interleaved? fields per entry?) and the limit behavior. It conveys the content categories adequately but leaves the result structure and the sole parameter undefined.

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 single 'limit' parameter (max 50, min 1) has 0% schema description coverage and is never mentioned in the description. The description should compensate by explaining that limit caps the number of movers returned, but it does not.

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 names the resource precisely — fastest-moving agent repositories on GitHub measured by star deltas, plus newly seen MCP servers — which an agent can distinguish from search_mcp_servers or what_agents_want. It lacks an explicit verb (list/retrieve), but the content is specific enough to act on.

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 versus siblings such as search_mcp_servers or what_agents_want. The 'this week's' phrasing implies a trending/novelty-discovery use case, but nothing tells the agent when this tool is the right choice over the alternatives.

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 behavioral burden. It discloses that the request is free, stored as a short label, should not include personal data, and returns closest paid services if any, but omits permissions, rate limits, visibility/lifecycle of the stored request, and exact response shape.

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 short sentences front-load the trigger, then give input/privacy guidance and return behavior. There is no filler, and every sentence contributes to correct invocation.

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 no annotations and no output schema, the description gives enough to understand the main request flow and privacy constraint. However, it leaves the 'category' parameter unexplained and does not cover auth, rate limits, or what happens to the stored request.

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 carry all parameter meaning. It explains 'what' and 'max_price_usdc' (per call, USDC) but never explains 'category', leaving two of three parameters with semantic help and one undocumented.

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 opening question plus 'Say what it is' and 'Returns the closest paid services' makes it clear this submits a capability request and returns possible paid services. It is distinguishable from search_mcp_servers by the demand-signal framing, though it does not name 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?

It explicitly targets the 'Could not find a tool or data source you need' case, which is a clear trigger. It does not name search_mcp_servers or any when-not condition, so it stops short of a 5.

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 behavioral burden. It usefully discloses temporal scope and result metadata (purpose label and whether the server charges per call), but it omits key operational details such as read-only behavior, authentication needs, result limits, pagination, and sorting. This is adequate but leaves clear gaps.

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 front-loaded sentence with no wasted words. It efficiently packs the core action, temporal scope, matching mode, and relevant result metadata.

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 two-parameter search tool, the description gives enough to understand the main action and result shape. However, with no annotations and no output schema, it should more clearly explain parameter optionality, the purpose filter, and basic return behavior to be 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?

Schema description coverage is 0%, so the description must compensate for both parameters. It implies that search is by name and mentions purpose labels read/act/transact, but it omits the enum value 'other' and never clarifies that the purpose parameter acts as a filter. It also does not state that both parameters are optional.

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 verb and resource: search MCP servers, with a clear scope of servers published or updated this week and matching by name. The sibling tools are unrelated, so there is no ambiguity to resolve. It also previews result attributes (purpose label and per-call charging), making the tool's purpose immediately understandable.

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 a use case by mentioning servers published or updated this week, but it does not state when to use this tool, when not to use it, or what alternatives exist. The sibling tools are not mentioned as alternatives, and no prerequisites or exclusions are 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 exist, so the description carries the full burden, and it does not say whether this is read-only, whether the data is cached or live, how fresh it is, or how heavy the call is. The phrase 'summary' implies aggregation but nothing about cost, scope limits, or return shape is disclosed.

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?

A single densely-packed sentence that front-loads the organizing concept ('the three-scale summary') before listing the parts. Nothing is redundant, though the parenthetical sourcing makes it denser than it needs to be.

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-param tool with no annotations and no output schema, the description should at minimum convey what the response roughly contains or how the three sections are structured. It names the three domains but not the returned shape, and leaves 'blackhull' undefined, so an agent cannot fully predict the payload.

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 there is no parameter semantics to document. Baseline 4 applies; the description correctly gives no parameter guidance because none is needed.

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 enumerates three specific data domains (crawler fetch reasons, tool-building purposes, visiting agents), which is more informative than a tautology. But it is a noun phrase with no verb and no statement of what the tool actually returns or does — an agent must infer it is a read-only aggregate report. The reference to 'blackhull' is unexplained.

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 versus the sibling tools (economy_movers, dispute_finding, search_mcp_servers), nor any prerequisite or exclusion. The agent is left to guess whether this is an overview to call first or a niche report.

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