byte-protocol

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

Far exceeds the annotations: it discloses the EIP-3009 signing flow, the facilitator submitting the tx, the required PRIVATE_KEY env var, the need for USDC on the wallet, that real USDC settles on Base mainnet (eip155:8453), that the attestation proves delivery not correctness, and advises a dedicated wallet. This is exactly the safety context annotations alone cannot carry.

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?

Purpose and settlement model are front-loaded and every sentence carries information, but the feeds catalog URL is repeated three times and the pricing/URL material could be consolidated without loss.

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 paid, non-idempotent, open-world mutation tool with an output schema, the description supplies everything the agent needs to act correctly: auth prerequisites, chain/currency, price discovery path, and the semantic limits of the returned attestation.

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 ties the parameters to a behavioral switch (omitting `body` = GET, supplying it = POST) and enumerates which oracle families require it, adding decision-level meaning beyond the schema's type declarations.

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+scope: 'Buy a single data packet from any PayPerByte feed via the x402 payment gateway.' It explicitly names the alternatives it is not (byte_subscribe for streams, byte_query_fact for fact Q&A), so an agent can route without opening schemas.

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 when-to-use/when-not rules: GET feeds need only `feed`, POST oracles need `body`, and 'supplying body switches this call to POST.' It also routes the agent to byte_subscribe for continuous streams and byte_query_fact for fact oracles.

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, destructiveHint=false, so the description's lack of explicit safety caveat is acceptable. However, the description does not add behavioral context beyond the annotation: it doesn't mention response details (e.g., whether it returns boolean, subscription info), or if any edge cases (e.g., invalid addresses) exist. It adds minimal value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that clearly conveys the tool's purpose. It is front-loaded and has no unnecessary words or 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?

Given the tool's simplicity (two simple parameters, both documented, with a clear purpose), a single sentence is likely sufficient. The output schema exists, so return details are covered by that. However, the description could benefit from telling the agent whether the tool returns a boolean, status, or detailed subscription info, but that may be unnecessary given the output schema. It's minimally complete but not rich.

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 each parameter has a clear description ('Subscriber Ethereum address', 'Publisher Ethereum address'). The tool description rephrases the parameters but doesn't add deeper semantic context (e.g., how these addresses are used, what format is expected beyond '0x...', or any relationship to the subscription). Since the schema already covers the parameters, the description adds little extra semantic value.

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 an address is subscribed'), the specific resource (a subscription on PayPerByte), and the key entities (address and publisher). It distinguishes itself from siblings like byte_list_my_subscriptions (which lists current user's subscriptions) and byte_subscription_health (which likely assesses 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?

While the description implies the tool is for checking a specific subscription status given an address and publisher, it does not provide explicit guidance on when to use this versus alternatives like byte_list_my_subscriptions, byte_subscription_health, or byte_get_token_balances. No exclusions or alternative suggestions are given.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful network context about MockUSDC and settlement, but no additional behavioral traits like failure modes or response characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler; the core scope is front-loaded and the clarifying exclusion follows immediately. Every sentence earns its place.

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 one fully documented parameter, a rich output schema, and annotations covering safety, the description is complete enough for correct invocation. It also covers the important cross-network distinction that could otherwise cause misuse.

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 the single 'address' parameter, so the schema already fully documents it. The description does not add parameter-specific semantics beyond what the schema provides.

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 USDC and ETH balances for an address') with precise network scope (Arbitrum Sepolia) and explicit exclusion of Base-mainnet balances. Clearly differentiates from 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?

Explicitly says this tool does NOT return the Base-mainnet USDC balance that byte_buy_data spends, telling an agent when this tool is not appropriate. This gives clear routing guidance relative to a relevant sibling.

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 destructiveHint, so the safety profile is covered. The description adds useful behavioral context: only 'active' feeds are returned, and it discloses that pricePerKB is a deprecated alias, which prevents agents from misinterpreting that field.

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 entire description is one focused sentence with no filler. The core action and scope are front-loaded, and the deprecated-alias note is appended without bloating the text.

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 parameters, an output schema present, and annotations covering safety, the description provides all necessary context: what is listed, the filtering ('active'), and what fields the agent should expect. Nothing essential 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?

There are zero parameters, so the baseline is 4 and there is nothing to explain. The description's mention of returned fields like topics and price-per-call is helpful even though it is technically output semantics rather than parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('List'), a distinct resource ('all active data feeds in the PayPerByte catalog'), and summarizes the returned information. It distinguishes this from sibling tools like byte_list_my_subscriptions by emphasizing the catalog-wide 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 phrase 'all active data feeds in the PayPerByte catalog' gives clear context for when to use this tool: when an agent needs a catalog-wide overview rather than user-specific subscriptions or publisher details. It does not explicitly name alternatives or state when not to use it, but the context is strong enough.

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

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

Annotations already declare 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?

The description adds meaningful behavioral context beyond the annotations by explaining what the action entails: 'Hashes the payload, records size on-chain, and settles the fee in USDC.' This is consistent with the destructiveHint and readOnlyHint in the annotations, and it discloses the side effects clearly.

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, front-loaded with the primary action, and every sentence adds value. It is concise without excessive detail, making it easy for an agent to quickly grasp the tool's purpose and key behavior.

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 (a write operation with fee settlement), the description covers the essential behavioral aspects: hashing, on-chain recording, fee settlement, and the private key requirement. The presence of an output schema and full parameter descriptions fills the remaining gaps, making this 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?

All three parameters are fully described in the input schema, so the description does not need to add parameter-level details. The description's mention of hashing and settling fees partially clarifies the purpose of 'data' and 'maxFee', but does not significantly exceed what the schema already provides. Thus, 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 the action: 'Publish data to a subscriber via the PayPerByte DataStream contract.' This is a specific verb and resource that distinguishes it from sibling tools like 'subscribe' or 'buy_data'. The purpose is 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 that this tool is used to publish data to a subscriber, but it does not explicitly state when to use it versus alternatives. It does mention a prerequisite ('Requires PRIVATE_KEY'), which provides some usage context, but there is no explicit guidance on when to prefer this tool over other byte_* 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?

The description goes well beyond the annotations, disclosing behaviors an agent needs to know: the tool performs an on-chain posting (spend/state-changing despite destructiveHint=false, consistent with readOnlyHint=false), it blocks waiting for a broadcast with a hard timeout, it returns a signed receipt proving provenance but explicitly NOT correctness, and it fails with a timeout rather than an answer when no publisher is live. The openWorldHint=true annotation is echoed by the description's honest framing of answers as grounded-in-citations rather than guaranteed facts. No behavioral surprises are left undisclosed.

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 well-structured: three sentences that front-load the purpose, then unpack mechanics, then the correctness caveat, then availability/timeout behavior. Each sentence carries distinct information — no filler or repetition. The length is justified by the tool's complexity (on-chain interaction, billing, subscription requirements, timing). It could be tightened slightly (e.g., 'PayPerByte' and 'fact-oracle' are each repeated), but the structure makes the key facts easy to scan.

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 — 6 parameters, on-chain posting, paid queries, subscription prerequisites, broadcast timing variance, and an output schema — the description covers the essential context: the full request lifecycle (post → wait → return), the timeout failure mode, the billing model (price-per-KB, refusal if over budget, cross-reference to publisher lookup tools), and the epistemic caveat that the signed receipt attests provenance not correctness. Minor gaps exist (e.g., behavior on partial failures like insufficient escrow mid-flight), but those are reasonably delegated to the output schema.

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% — every one of the 6 parameters has a rich description including examples, units (BPS scale, ms, bytes), enums-like explanations (9000=Elite-only, 7500=Premium+), cross-tool references, and hard constraints (regex pattern, min/max bounds). Per the rubric, high coverage (>80%) sets the baseline at 3; the main description adds no parameter-level semantics beyond what the schema already provides, which is appropriate given the schema's thoroughness.

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 leads with a specific verb–resource–outcome triplet ('Query a PayPerByte fact-oracle publisher for a signed answer with citations') and then details the mechanism (posts question on topic='fact-oracle', waits for on-chain broadcast, returns answer plus citation URLs). It clearly distinguishes this tool from the sibling set — it is the query-side counterpart to byte_publish_data, the consumer of byte_search_publishers/byte_get_publisher, and the producer of payloads that byte_verify_payload would verify.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong situational guidance: it explains the on-chain broadcast flow, the timeout behavior when no publisher is live, and the crucial caveat to ground outputs in cited sources rather than trusting the signed answer. Parameter-level docs reinforce when-to-use details by naming sibling tools ('read it with byte_get_publisher or byte_search_publishers before asking') and specifying the subscription prerequisite ('You MUST be subscribed... or the publisher's on-chain broadcast will be skipped). It stops short of explicitly saying 'use this instead of X for scenario Y' for a named alternative, but the guidance is nevertheless concrete and actionable.

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 a destructive, non-read-only operation. The description adds important context: requires PRIVATE_KEY, registers on-chain, and explains the stake approval flow. This goes beyond what annotations provide and shows 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?

Four concise sentences, front-loaded with the core purpose, and every sentence contributes new information. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a registration tool with six parameters and an output schema, the description covers the essential context: purpose, on-chain side effects, private key requirement, and stake behavior. It does not detail parameter relationships or prerequisites beyond stake, but remains complete enough for an agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All six parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description adds a little extra meaning, mainly reinforcing the stake parameter's default and approval step, but does not significantly compensate for any missing parameter detail.

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 ('Register as a data publisher') and specifies that it 'Registers a schema and the publisher on-chain.' This is specific and distinguishes it from sibling tools like byte_publish_data or byte_subscribe.

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?

Provides explicit usage guidance for the stake parameter ('leave stake at 0') and notes the approval requirement for non-zero stakes, giving practical context. However, it does not explicitly name alternative tools or state when not to use this 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?

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?

The description goes well beyond the readOnlyHint/idempotentHint annotations by explaining the exact mechanism (recompute keccak256 and compare to EIP-712 PayloadAttestation hash), the signer-recovery behavior when txHash is provided, and the operational consequence of verified=false. It also states 'Read-only; no wallet or payment required,' adding auth/context value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet information-dense. It front-loads the core purpose with 'Verify-before-act', immediately states the critical safety rule, then supplies anchoring options and read-only status. Each sentence contributes distinct value 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?

Given the tool's moderate complexity, the description covers the full lifecycle: what it does, when it must be used, both verification modes, failure semantics, and read-only/auth implications. The presence of an output schema means return-value details are already handled, so the description is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage semantics beyond the schema: expectedHash is sourced from byte_query_fact/byte_buy_data, txHash recovers the attestation signer, and hashMode 'raw' matches byte_publish_data. This enriches parameter understanding without duplicating 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 names a specific verb and resource: verify a data payload against an on-chain attestation hash. It clearly distinguishes this from sibling tools by framing it as the verify-before-act counterpart to publish/query/buy data operations.

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 states when to call the tool ('ALWAYS call this on BYTE-sourced data before acting on it'), what to do on failure ('if verified=false the bytes were tampered/corrupted... MUST NOT be used'), and how to anchor the check with either expectedHash or txHash. This is strong, actionable usage guidance.

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