byte-protocol

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

The description reveals critical behavioral traits beyond annotations: EIP-3009 authorization signing, x402 facilitator submission, inline data return with tx hash, and the warning about real USDC settlement on Base mainnet with quoted prices. It advises using a dedicated wallet for spending, which is essential risk disclosure not present in annotations. No contradiction with the readOnlyHint=false annotation.

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 longer than average but information-dense; every sentence carries weight (payment mechanism, alternatives, prerequisites, cost warning). It is front-loaded with the core purpose, followed by necessary operational details. Slight verbosity in enumerating feed slugs and prices is justified given the tool's complexity, but it could be tightened without losing value.

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 payment-involving tool with nested object parameters and an output schema, the description covers all necessary context: prerequisites, on-chain settlement, costs, GET/POST behavior, and safety warnings. The existence of an output schema covers return-value details, so the description's lack of explicit return format is acceptable. It is complete for the tool's complexity.

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% with detailed descriptions, but the tool description adds real-world examples and context (e.g., body structures like {domain,address} for address-reputation) that go beyond the schema's generic object definition. It clarifies how the `body` parameter toggles POST and lists which specific feeds require it. This adds practical semantic value despite overlap with 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?

The description states a specific action ('Buy a single data packet from any PayPerByte feed via the x402 payment gateway') with a clear resource and mechanism. It distinguishes itself from siblings by explicitly mentioning 'Use byte_subscribe instead if you want a continuous stream' and in the feed parameter notes 'byte_query_fact' for different flow. The purpose is unambiguous and well-differentiated.

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 explicit when-to-use guidance: 'Use byte_subscribe instead if you want a continuous stream of broadcasts'. It also details prerequisites (PRIVATE_KEY env var, USDC on Base mainnet), clarifies the GET vs POST distinction based on feed type, and names byte_query_fact as an alternative for fact-oracle Q&A. This fully addresses when and when-not to use the tool.

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 the tool as readOnlyHint, idempotentHint, and non-destructive. The description is consistent with these, but it adds no extra behavioral context beyond what annotations and schema already imply. For a simple read-only check, this is sufficient.

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 sentence, front-loaded with the action verb and key objects. It communicates the essential purpose without any unnecessary words 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?

This is a simple read-only tool with two fully documented parameters, clear annotations, and an output schema. The description, combined with the schema and annotations, provides all necessary information for an agent to correctly invoke the 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 input schema provides full descriptions for both parameters (subscriber and publisher) as Ethereum addresses, with 100% coverage. The description does not add further semantic detail, so it relies on the schema, which is 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?

The description clearly states the action ('Check if') and the exact resources involved ('an address', 'a specific publisher', 'subscription'). It distinguishes itself from sibling tools like byte_subscribe (creation) and byte_list_my_subscriptions (listing own subscriptions).

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 use case: verifying a specific subscriber-publisher pair. However, it does not explicitly mention when to prefer this over alternatives like byte_subscription_health or byte_list_my_subscriptions, and offers no exclusions or prerequisites.

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 indicate safe read-only, idempotent, non-destructive behavior. The description adds context about what statistics are returned (publishers, messages, fees), but does not disclose additional behaviors like pagination or latency. With annotation coverage, this is adequate but not rich.

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 sentence that front-loads 'Get' and the resource name, then enumerates the specific statistics. No wasted words or 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?

With zero parameters and an output schema present, the description fully covers what the tool does. It clearly states the scope (network-wide) and the key data points (publishers, messages, fees), making it complete for the tool's simplicity.

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 0 parameters, so the baseline is 4. The description adds no parameter information because none is needed; the schema fully covers the (empty) parameter set.

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 ('Get') and specific resource ('PayPerByte network-wide statistics') with concrete details (total publishers, messages streamed, USDC fees). This clearly distinguishes it from sibling tools that target individual publishers or specific 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?

The description implies this tool is for global network statistics versus publisher-specific tools like byte_get_publisher or byte_list_feeds, but it doesn't explicitly state when to use it or name alternatives. The context is clear but no exclusions or comparisons 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by enumerating the exact data returned (status, counts, revenue, schema), giving context beyond the annotations without contradicting them.

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, front-loaded sentence with a clear verb and a parenthetical list of returned fields. No unnecessary words or 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?

For a simple one-parameter read-only tool with an output schema present, the description adequately covers the tool's function and output. The sibling context confirms its specific niche, and no critical information 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 for the single 'address' parameter is 100%, and the schema already describes it as a 'Publisher Ethereum address (0x...)'. The description does not add new parameter-level meaning but is consistent with the 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?

The description clearly states the tool's purpose: 'Get on-chain info for a specific PayPerByte publisher' with a detailed list of returned data. The verb 'Get' and resource 'specific PayPerByte publisher' distinguish it from sibling tools like byte_search_publishers or byte_list_feeds.

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 a specific publisher but does not explicitly state when to use it over alternatives or mention exclusions. The phrase 'specific PayPerByte publisher' suggests this is for fetching details by address, but no direct comparison to sibling tools is 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?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond this, such as the testnet nature of Arbitrum Sepolia, the role of MockUSDC in settling subscriptions and fact-oracle queries, and the exclusion of Base-mainnet balances. This helps the agent understand the operational context and constraints.

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 concise and well-structured: two sentences, with the main action front-loaded in the first sentence and critical clarification in the second. Every sentence adds value 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?

For a simple read-only tool with one parameter and an existing output schema, this description is highly complete. It specifies the exact tokens, network, the address scope, and explicitly mentions what it does not include, providing sufficient context for correct tool selection.

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 provides 100% coverage for the single 'address' parameter with a clear description ('Ethereum address (0x...)'). The tool description adds no additional parameter-specific information, so baseline 3 is appropriate since the schema carries the semantic weight.

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 function: getting USDC and ETH balances for an address on Arbitrum Sepolia. It specifically names the tokens and network, and distinguishes from sibling tool byte_buy_data by explicitly stating what it does NOT show, making the purpose 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?

The description provides clear context for when to use this tool: when checking USDC/ETH balances on Arbitrum Sepolia, and it explicitly notes it does not show Base-mainnet USDC spent by byte_buy_data. This implies the alternative for Base-mainnet balances but does not explicitly say 'use byte_buy_data for that', so it is not a full when-to-use guide.

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, openWorld, idempotent, and non-destructive. The description adds 'all active' (filtering behavior) and mentions the included fields, providing useful context beyond the annotations. No contradictions.

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, verb-first, with all key elements (what, where, content). No filler or redundant phrasing. Extremely efficient.

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's simplicity, the presence of an output schema, and rich annotations, the description is complete. It covers purpose, scope, and content fields, leaving no critical 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?

The input schema has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description doesn't need to compensate. It correctly omits irrelevant parameter details.

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 ('List'), identifies the resource ('all active data feeds in the PayPerByte catalog'), and adds content details (topics, price-per-KB, frequency). It distinguishes itself from siblings like byte_list_my_subscriptions by explicitly naming the catalog scope.

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: it's a catalog-wide listing of active feeds. It doesn't explicitly name alternatives or exclusions, but the phrasing implies usage for discovering available feeds. No misleading guidance.

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 and idempotentHint=true. The description goes beyond by enumerating the exact return fields (publisher address, topic, status, subscription date, message counts, USDC spent, last message timestamp) and clarifying it lists only active subscriptions. It does not mention pagination or error behavior, but that is acceptable for a read-only list.

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 action verb and resource. The field list is compact and the use case sentence adds value without unnecessary prose. 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?

An output schema is present, so return structure is documented elsewhere. The description covers purpose, resource, fields, and intended use. It is complete for a simple read-only listing tool with no complex edge cases or side effects.

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 both parameters. The description adds no new meaning beyond the schema; it simply references the subscriber as 'a given wallet address.' Since the schema already documents indexerUrl and subscriber with descriptions, the baseline of 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?

The description uses a specific verb+resource: 'List every active subscription for a given wallet address.' It clearly differentiates from siblings like byte_list_feeds (feeds vs subscriptions) and byte_check_subscription (single vs all). The detailed field list further clarifies the scope.

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 a clear use case: 'Use this to see what you're currently paying for and decide whether to unsubscribe.' This gives context for when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full exclusion guidance.

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 (destructive, open world, etc.), the description adds valuable context: it hashes the payload, records size on-chain, and settles fees in USDC. It also discloses the PRIVATE_KEY requirement. This significantly enriches the agent's understanding of side effects and preconditions, with no contradiction to 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, front-loaded with the primary purpose, followed by core mechanics and a critical requirement. Every sentence earns its place; there is no redundancy or unrelated 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?

The description covers the essential behavior, side effects, and prerequisites for a moderately complex publish operation. With an output schema present, return values are handled separately, and the description is sufficient for an agent to select and 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?

Parameter descriptions in the schema already fully cover each field (100% coverage), including that the data will be hashed and that maxFee is in USDC. The tool description does not add new parameter-specific meaning beyond what the schema provides, so the baseline of 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?

The description states a specific action ('Publish data to a subscriber') and names the exact contract (PayPerByte DataStream). It clearly distinguishes this from sibling tools like byte_buy_data or byte_subscribe by focusing on the publish operation, and adds defining mechanics (hashing payload, recording size, settling fee).

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 makes it evident when to use the tool (to publish data to a subscriber) and mentions a key precondition (requires PRIVATE_KEY). It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to select it over 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?

The description goes beyond annotations by detailing the on-chain interaction, the signed receipt's evidentiary limits, and the timeout behavior when no publisher is live. This adds significant transparency about external dependencies and result interpretation beyond the basic flags.

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 three sentences, with the core purpose in the first sentence, followed by caveats and availability. No redundant information; each sentence adds value.

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 a full output schema and thorough parameter documentation, the description covers the operational context, failure mode (timeout), and interpretational caveat (provenance != correctness). It is complete enough for an agent to invoke correctly and process the response appropriately.

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 already provides 100% description coverage, with each parameter having detailed descriptions including defaults, constraints, and examples. The tool description does not add additional parameter-level semantics beyond referencing the question posting and timeout, so the baseline of 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?

The description clearly states the tool's function: 'Query a PayPerByte fact-oracle publisher for a signed answer with citations.' It specifies the resource (fact-oracle publisher), action (query), and output (signed answer with citations), distinguishing it from sibling tools like byte_publish_data or byte_verify_payload.

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 provides clear context by explaining the query flow (posts question, waits for broadcast, returns answer) and crucial guidance that the signed receipt proves provenance but not correctness, instructing users to ground output in cited sources. It also mentions the availability requirement of a registered publisher, but does not explicitly name alternative tools for other use cases.

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?

While annotations already indicate this is a destructive/write operation, the description adds valuable context: it is an on-chain operation, requires PRIVATE_KEY, and details the stake approval flow (USDC approval to DataRegistry for non-zero stakes). This goes beyond the annotation hints and sets clear expectations for side effects.

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 primary purpose, followed by essential prerequisites and parameter-specific guidance. Every sentence earns its place with no redundant or vague content.

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's complexity (on-chain registration) and the presence of an output schema, the description covers key prerequisites (PRIVATE_KEY), the main action (register schema + publisher), and important stake behaviors. It doesn't mention potential overwriting or network-specific details, but the output schema and annotations fill in structural gaps, leaving the description reasonably 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 100%, so the baseline is 3. The description adds context for the 'stake' parameter, explicitly advising to leave it at '0' and explaining the approval mechanism for non-zero values. Other parameters are adequately described by the schema, so no significant extra value is added.

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 ('Register as a data publisher on PayPerByte') and clearly differentiates from siblings like byte_publish_data by specifying it registers a schema and publisher on-chain. The title 'Register publisher' reinforces the purpose, making it 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?

The description provides clear context on when to use the tool: first-party publisher registration, and explicitly notes the need for PRIVATE_KEY. It doesn't explicitly state when not to use it or mention alternatives, but the context is sufficient to avoid confusion with data-publishing or subscription tools.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and side-effect transparency. The description adds concrete behavioral details about the return fields (addresses, topics, subscriber counts, message counts, price-per-KB) and the search/sort behavior, which is useful beyond the annotations. No contradiction.

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, well-structured sentence that front-loads the core action and includes essential return information. Every word earns its place, with no redundancy or fluff. It is appropriately sized for a simple search tool.

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's simplicity (3 optional params, no required args, no nested objects) and the presence of an output schema (as per context signals), the description fully covers what the agent needs: what it searches, how results are ordered, and what fields are returned. The annotations and schema handle the rest. This is complete for a search 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 coverage is 100%: all three parameters (limit, query, sortBy) have descriptions in the schema. The description adds no extra parameter meaning beyond what the schema already provides. The mention of 'topic' and 'sort order' mirrors the schema fields, so the baseline score of 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?

The description specifies the exact action ('Search PayPerByte publishers') and scope ('by topic and sort order'), clearly distinguishing it from siblings like byte_get_publisher (likely single publisher lookup) and byte_list_feeds (listing feeds). The verb 'Search' plus the explicit resource and modifiers makes the purpose 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?

The description implies usage: use this when searching publishers by topic with sort/limit options. It does not explicitly mention alternatives or exclusions, though the sibling tool names provide context. Without explicit 'when to use vs. alternatives' guidance, it falls at the 'implied usage' level.

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 description goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by detailing the default USDC allowance behavior, the allowance-skip path with its silent payment loss mitigation, the `skipAllowance` opt-out, and the PRIVATE_KEY requirement. It also explains the contract's transferFrom failure behavior, providing deep behavioral insight that helps the agent predict side effects.

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 concise (three sentences) and front-loaded with the main purpose. Each subsequent sentence adds distinct value: the allowance default, the skipAllowance option, and the PRIVATE_KEY requirement. While it is a bit dense with technical details, it is appropriately sized for the complexity and does not contain 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 existence of an output schema and the moderate complexity of the tool, the description covers all essential aspects: what the tool does, the default allowance behavior, the opt-out path, and a critical requirement (PRIVATE_KEY). It doesn't need to describe return values because the output schema exists, and it provides enough context for an agent to select and invoke the tool correctly without additional information.

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 already describes the `publisher` and `skipAllowance` parameters with 100% coverage. The description adds a small but useful nuance: 'Pass skipAllowance: true to opt out and set a finite cap manually.' This adds a new semantic (finite cap) not explicitly mentioned in the schema, slightly enhancing the parameter understanding. Given the high schema coverage, a score of 4 is appropriate for the extra value added.

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: 'Subscribe to a PayPerByte publisher's data feed.' It uses a specific verb ('Subscribe') and resource ('data feed'), and it adds the key behavior of setting an allowance, which distinguishes it from sibling tools like byte_buy_data or byte_unsubscribe. The scope is unambiguous and aligns with the tool name.

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 a clear context for when to use the tool (when you want to subscribe to a data feed), but it does not explicitly mention alternatives or when-not-to-use cases. It does explain the `skipAllowance` option, which is a parameter-level guideline, but there is no explicit comparison to sibling tools like byte_buy_data or byte_list_my_subscriptions. This is implied rather than explicitly stated.

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 and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral detail beyond annotations: the comparison window (7 vs 23 days), specific thresholds for 'moderate' and 'significant', and the 'unknown' case for new publishers. This enriches the agent's understanding of expected behavior and edge cases.

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 concise and well-structured: a single opening sentence states the core purpose, followed by a sentence on the computation method, then one on return values and intended use. Every sentence earns its place with no fluff, making it easy to scan and understand.

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 and annotations covering read-only/idempotent safety, the description fully explains the tool's reasoning and result categories, which is sufficient context for a moderate-complexity tool. It covers the essential logic, edge cases, and usage intent without needing to explain return structure.

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% with descriptive parameter names and inline descriptions ('Publisher address to check' and 'Optional indexer URL override'). The tool description adds no new parameter-level semantics beyond what the schema already provides, 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 clearly states what it does: 'Get the content-drift signal for a publisher.' It specifies the exact computation (last 7 days vs 23-day baseline) and return categories. This unambiguously distinguishes it from siblings like byte_check_subscription or byte_get_publisher, which target different aspects of subscriptions or publisher 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?

The description provides an explicit use case: 'Use this to detect when a publisher you subscribe to has pivoted content or gone dormant.' This tells the agent when to invoke the tool, but it does not mention when not to use it or name alternative sibling tools, so it falls short of a 5 for explicit when/when-not/alternatives guidance.

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 description adds valuable behavioral context beyond annotations: it discloses the timing effect ('next block'), the consequences ('no more billing, no more data flow'), reversibility, and the authentication requirement (PRIVATE_KEY). This complements the annotations (readOnlyHint=false, destructiveHint=false) without contradicting them.

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 concise and front-loaded with the main action, then adds key details in just three sentences. Every sentence provides essential information—purpose, effects, reversibility, use case, and auth—without waste.

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 tool with good annotations and an output schema, the description fully covers the lifecycle: when to use, what happens, reversibility, and prerequisites. There are no critical gaps; it elegantly combines purpose, usage, and technical effect.

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% with the parameter described as 'Publisher address to unsubscribe from,' which is clear. The description doesn't add extra parameter semantics, but the baseline for full schema coverage is a 3, and the description's mention of 'publisher' aligns with the schema. No additional insight 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 clearly states the action: 'Unsubscribe from a publisher's data feed.' It uses a specific verb and resource, and distinguishes itself from sibling tools by immediately referencing the reverse operation (byte_subscribe) and the health check tool (byte_subscription_health).

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 provides when to use: 'when a publisher has pivoted content... or when you simply don't want the feed anymore.' It also names alternatives like checking byte_subscription_health first and resubscribing via byte_subscribe, giving clear guidance on tool selection.

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 readOnlyHint/idempotentHint annotations, the description discloses the verification algorithm, the consequence of a failed check (tampered/corrupted), and the signer-recovery behavior when txHash is provided. It also states 'Read-only; no wallet or payment required', adding clarity that no transaction is needed.

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: purpose, algorithm, mandatory usage, failure handling, and parameter guidance. It is front-loaded with 'Verify-before-act' and remains readable despite being safety-critical.

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 correctly avoids re-explaining return values. It covers the tool's purpose, usage rules, verification logic, parameter selection, and non-destructive nature. Combined with annotations and the 100% schema coverage, no gaps remain.

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 already describes all four parameters in detail (100% coverage), so the baseline is 3. The description adds the meaningful EITHER/OR relationship between expectedHash and txHash, and clarifies that 'data' is the exact received payload bytes. This elevates it to a 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?

The description opens with 'Verify-before-act: confirm a data payload...' and specifies the exact operation: recompute keccak256 and compare to the on-chain EIP-712 PayloadAttestation hash. It clearly distinguishes this from sibling tools by naming it as the verification step for BYTE-sourced data and referencing expectedHash from byte_query_fact/byte_buy_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?

The description gives an explicit when-to-use: 'ALWAYS call this on BYTE-sourced data before acting on it'. It also provides a clear safety rule (if verified=false, bytes MUST NOT be used) and explains the two alternative anchoring parameters (expectedHash or txHash), with txHash additionally recovering the signer.

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