flipr-x402

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

With no annotations provided, the description carries the full burden. It discloses that the tool is 'FREE — rate-limited only' and enumerates the data fields returned. The read-only nature is implied by 'look up' but not explicitly stated; however, for a simple stats lookup, this is sufficient behavioral context.

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

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

The description is two sentences, front-loaded with the action and return values, followed by usage guidance and a free/rate-limit tag. Every sentence adds value with no 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 single-parameter lookup tool with no output schema, the description covers purpose, return fields, when to use, and cost/limitations. It is self-contained and gives the agent sufficient context 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?

The schema already describes the agentId parameter with 100% coverage ('The agent ID to look up'), so the description adds little beyond baseline. It mentions 'any agent' but does not elaborate on ID format or how to discover agent IDs, which is acceptable given the schema coverage.

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 with a specific verb ('Look up') and resource ('any agent's Flipr statistics'), and enumerates the exact statistics returned (heads streak, max streak, total flips, total wins, wallet balance). This distinguishes it from siblings like flipr_list_agents or flipr_referral_stats.

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 usage guidance: 'Use this to scout competition before flipping' and explains the strategic implication ('if the top streak is low, it may be cheap to match or beat'). It does not explicitly name alternative tools, but the context is clear 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?

With no annotations provided, the description carries the full burden and excels: it implies a read-only operation via 'Poll status', enumerates return fields (status, failureClass, credited, nextAction), and discloses payment network support, rate limiting, and free pricing. The nextAction instruction adds behavioral depth by telling the agent exactly how to proceed.

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 front-loaded with the core purpose, then efficiently covers return fields, usage instructions, payment networks, documentation link, and pricing. Every sentence contributes unique, non-redundant information, and the structure is logical and scannable.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete: it explains the trigger condition, return values, nextAction semantics, and relevant constraints (payments, rate limiting). It provides an agent with everything needed to invoke and interpret results.

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

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

The schema already covers the single parameter bridgeId comprehensively, including its format ('base58, ~88 chars') and origin ('returned in the 202 response'). The description reinforces this context but adds no new parameter-specific information beyond that, so the baseline score 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 tool's purpose with a specific verb ('Poll status') and resource ('Solana payment bridge'). It distinguishes itself from siblings by referencing the 202 response from flipr_flip and focusing on bridge state, making its role 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 explicitly specifies when to use the tool ('after a 202 response from flipr_flip') and provides actionable guidance on interpreting nextAction to decide next steps. It does not explicitly name alternative tools or when-not-to-use, but the workflow context is clear 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It covers return fields, streak persistence, pot awards, jackpot requirements, costs, payment networks, auto-bridging, dynamic pricing, and where to read live values. This is exceptionally transparent for a financial transaction tool.

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

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

The description is lengthy but each sentence adds meaningful information—streak rules, cost structure, payment networks, dynamic pricing, and prerequisite reads. It is dense rather than padded, but the lack of structured formatting and the embedded metadata tags make it slightly harder 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?

The tool is complex: multi-network payments, dynamic pricing, streak persistence, and contract-dependent jackpot targets. The description covers return values, costs, where to get live pricing, and dependencies on other tools. It omits error handling and response format details, but no output schema exists and the core operational context is well covered.

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 covers 100% of parameters (ref and agentId) with descriptions, and the tool description does not add extra semantic meaning for these parameters. Since the schema does the heavy lifting, the baseline score 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 ('Execute a coin flip') and the resource (Flipr.bet) with specific network details (Base mainnet, Solana mainnet, Chainlink VRF). This distinctly separates it from sibling tools that handle stats, pot, opportunity, or withdrawal 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?

The description explicitly tells users to check flipr_opportunity for ROI analysis before flipping and to read the jackpot target from flipr_pot or flipr_opportunity. It names alternatives and provides contextual prerequisites, though it does not explicitly state 'use this when you want to flip' since that is implied by the name.

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

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

With no annotations provided, the description carries the full burden. It clearly signals a read-only operation via 'Retrieve static game rules' and 'static', and discloses cost explicitly with 'Free -- no payment required'. It also enumerates all returned data, offering good transparency without asserting any 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 compact and front-loaded with the primary purpose. Subsequent sentences expand on returns and usage. The duplicate mention of 'free' (once in prose and once as pricing metadata) is minor and does not detract from overall clarity.

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?

There is no output schema, so the description must explain return values, and it does so thoroughly: flip cost, randomness source (Chainlink VRF), pot payout rules (2-hour and jackpot), denomination model (ETH pots, USDC payments), and strategies (match vs beat). This fully covers the informational scope for a zero-parameter, read-only tool.

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

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

The tool has zero parameters and the input schema is empty, so there is nothing to explain. The description appropriately focuses on the output rather than parameters. The baseline for 0 params is 4, which is fitting here.

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 'Retrieve' and precisely names the resource: static game rules, denomination model, pot mechanics, and strategy explanations. It explicitly lists the contents (flip cost, Chainlink VRF, pot payout rules, etc.), which clearly distinguishes it from sibling tools like flipr_flip or flipr_pot.

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 explicitly instructs 'Call this first to understand the game before using other tools,' which provides clear when-to-use guidance. It does not explicitly mention when not to use or name alternatives, though the sibling list makes the context evident.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is 'Free -- no payment required,' which is useful cost behavior. It also lists the return contents (subsystem status, uptime, flip count), indicating a read-only health check, though it does not explicitly state read-only or auth requirements.

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, starting with the purpose, then usage, then cost. Every sentence provides value without unnecessary padding. The pricing JSON is an additional structured block and does not detract from readability.

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 health check tool with no params and no output schema, the description covers purpose, output contents, a usage scenario, and cost. It does not specify the exact format of the status output, but this is likely acceptable for a health check.

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 per the baseline rule, the score is 4. The description does not need to explain parameters, and the schema is empty with 100% trivial coverage.

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: 'Check gateway health' and details what it shows (subsystem status, uptime, flip count). This distinguishes it from siblings like flipr_status and flipr_bridge_status by focusing specifically on gateway health with a specific subsystem list.

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 usage guidance: 'Use to verify gateway is operational before attempting flips.' This gives a clear context of when to use the tool, though it does not mention when not to use it or name alternatives.

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

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

No annotations are provided, so the description carries the burden. It communicates that the operation is a read-style 'List' call and adds cost/rate-limit context ('FREE — rate-limited only'). However, it does not disclose return format, pagination behavior, or any authentication requirements, leaving some gaps for an agent.

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 largely efficient: two meaningful sentences covering purpose and use case, plus a compact pricing note. The appended pricing JSON is slightly redundant with the 'FREE — rate-limited only' text but does not make the description bloated.

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 simple list operation with three optional parameters and no output schema, the description provides adequate context: it names the result fields, explains the use case, and mentions rate limiting. It lacks explicit response shape documentation, but the described stats cover the essential output semantics.

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 schema fully documents the three parameters. The description adds slight semantic context by mapping 'total flips', 'last active time', and 'registration date' to the sortable fields, but this is not substantial beyond 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 uses a specific verb ('List') and resource ('all registered agents on the Flipr gateway') and clearly describes the returned activity stats. It distinguishes itself from sibling flipr_agent_stats by emphasizing the agent-wide, aggregated listing perspective.

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 explicitly states when to use the tool: 'discovering active competitors and assessing overall gateway activity.' It does not name alternatives or exclusions, but the use case context is clear enough for an agent to select it appropriately.

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

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

No annotations exist, so the description carries full burden. It discloses return values (twoHourPot, jackpot), strategy options and ROI interpretation, currency details (ETH, USDC via x402), jackpot target mechanism, and cost/pricing behavior. This exceeds a simple read-only hint and gives rich behavioral context.

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

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

The description is lengthy but information-dense; every sentence contributes to understanding purpose, output, strategies, ROI, payment, and usage ordering. It could be better structured with paragraphs or bullets, but it is not bloated or repetitive.

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

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

For a zero-parameter tool with no output schema, the description thoroughly explains what the response contains, how ROI is calculated, the difference between pot types, and operational context (free, rate-limited, call-first). No significant 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 tool has zero parameters, so schema coverage is trivially 100%. The description does not need to explain parameter semantics, and the baseline of 4 applies since no parameters exist to document.

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 a specific verb+resource: 'Analyze current Flipr.bet opportunity' and distinguishes itself from sibling tools by positioning as the pre-flip analysis step, explicitly referencing flipr_flip. It clearly differentiates between the 2-hour pot and jackpot mechanics.

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 instructs 'Call this FIRST before using flipr_flip', giving a clear when-to-use directive. It also contrasts with the 2-hour pot and states it is free and rate-limited, providing adequate context for when this tool should be selected over alternatives.

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

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

No annotations are present, so the description must convey behavioral traits. It discloses the tool is FREE and rate-limited, and clarifies the jackpot mechanic (target-based vs competitive), which helps interpretation. However, it doesn't explicitly state that it's a read-only operation or describe response ordering/pagination, leaving some gaps.

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

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

The description is three sentences: purpose, use case, and cost/mechanic. It front-loads the core function and omits fluff, making it highly scannable.

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

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

For a simple single-parameter tool with no output schema, the description covers purpose, use case, and relevant game mechanics. It mentions output content (ROI and pot data) but not the exact return shape, which is a minor gap. Overall, adequate 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?

The input schema describes the limit parameter fully with default and max values, giving 100% coverage. The description adds no additional parameter info, matching the baseline score of 3.

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 a specific verb 'Get' and identifies the resource as 'historical opportunity snapshots' with details on ROI and pot data, clearly distinguishing it from sibling tools like flipr_opportunity and flipr_pot that likely provide current state.

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 includes 'Useful for identifying trends in pot balances and optimal flip timing,' which gives a concrete use case and implies it should be used for historical analysis rather than current queries. It doesn't explicitly name alternatives, but the contrast is implicit in the name and context.

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

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

With no annotations, the description discloses key behavioral traits: POST delivery, payload contents (pot data and ROI), frequency (5 min), cost ($0.001 USDC), and payment network options (Base/Solana via auto-bridge). Does not mention response/return value or error handling, but covers the main operational behavior.

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?

Concise and front-loaded with the action, then details. The bracketed lines appear to be structured metadata and the localhost URL slightly clutters, but overall it's 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 complexity (webhook, payment, multi-network), the description covers the event trigger, payload, cost, payment networks, and a link for details. Lacks explicit return value or idempotency, but is 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 covers both parameters with descriptions (agentId, callbackUrl). Description adds no extra parameter-specific context, but the baseline for 100% coverage is 3.

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?

Clearly states the action ('Subscribe to webhook alerts for Flipr opportunity snapshots') with a specific verb and resource, and distinguishes from siblings like flipr_opportunity_unsubscribe by describing the subscription behavior.

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?

Describes when the webhook fires (every evaluation cycle, 5 minutes) and the cost model, which implies use case. Does not explicitly exclude alternatives or name sibling tools, but the behavior is clear 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?

With no annotations, the description carries the full burden and only says 'Remove' and 'FREE — rate-limited only'. It does not disclose side effects, reversibility, authentication needs, or what happens after removal.

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 core description is a single concise sentence, front-loaded with the action. The embedded pricing tag adds some non-essential detail but does not significantly hinder clarity.

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 tool, the description provides the basic purpose, but lacks information about return values, error conditions, or side effects, especially since there is no output schema or annotations.

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

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

The schema fully describes the sole parameter subscriptionId, so the baseline is 3. The tool description adds no additional meaning about the parameter beyond 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?

Description clearly states 'Remove an opportunity webhook subscription' with a specific verb and resource, making it easy to understand and distinguish from the sibling tool flipr_opportunity_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?

No guidance is provided on when to use this tool versus alternatives. The description only states the action and includes pricing/rate-limit info, but does not mention related tools or scenarios.

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

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

With no annotations provided, the description fully carries the behavioral transparency burden. It discloses that the tool returns ETH balances for the 2-hour pot and jackpot, includes top streak holders, indicates time remaining, and clarifies the jackpot is target-based with targetStreak and roundId in the response. It also notes the response field is twoHourPot (not fourHourPot) and that the tool is FREE with rate limiting. This is thorough and prevents expected misuse.

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 slightly dense but every sentence contributes value: purpose, returned data, usage hint, jackpot explanation, field-name correction, and pricing/rate-limit note. The embedded pricing JSON adds some noise but is structured and relevant. No fluff or tautology.

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 there is no output schema, the description must explain what the tool returns, and it does so comprehensively: 2-hour pot and jackpot balances, top streak holders, time remaining, targetStreak, roundId, and the exact field name 'twoHourPot'. It also mentions the rate limit. For a zero-parameter read tool, this is complete enough for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so the input schema provides no meaning. The description goes beyond by explaining the output structure (twoHourPot, jackpot, targetStreak, roundId) which is helpful for understanding the tool's behavior. Baseline for 0 params is 4, and the description adds value by describing response fields rather than leaving the agent to guess.

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: 'Get current Flipr.bet pot balances and competition state.' It specifies the resource (Flipr.bet pots) and the action (get balances/state), and lists key outputs (2-hour pot, jackpot, top streak holders, time remaining). This distinguishes it from siblings like flipr_game_info or flipr_flip, which focus on other aspects.

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 explicitly says 'Use this to monitor pot balances,' providing clear guidance on when to invoke this tool. It doesn't name alternative tools or provide exclusion criteria, but the use case is well-defined. For a read-only tool with zero parameters, this is sufficient context.

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

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

With no annotations, the description carries the full burden and does a good job. It explicitly states 'FREE — rate-limited only,' and indicates a read-only behavior by saying 'View' and 'Shows.' It also lists the fields returned. This is useful context beyond what the schema alone provides, though it could go further by mentioning any authentication requirements or data freshness.

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

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

The description is compact and front-loaded: two sentences plus a pricing JSON block. Every sentence adds value (purpose, output fields, and cost/rate-limit). 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?

The tool is simple with one optional parameter and no output schema. The description sufficiently explains the return contents (agent ID, referred volume, commission) and the ranking criterion. It could be a 5 if it explicitly noted descending sort order or pagination behavior, but the 'top' implies sorting and the limit parameter handles pagination.

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 'limit' parameter, which already documents default and max values. The description adds no additional parameter semantics, so it appropriately hits the baseline of 3.

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: 'View top referrers ranked by total commission earned.' It specifies the resource (top referrers) and the ranking metric. However, it does not explicitly differentiate from sibling tools like flipr_referral_stats or flipr_agent_stats, so it earns a 4 rather than a 5.

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 viewing a leaderboard but provides no explicit guidance on when to use this tool versus alternatives. There is no mention of 'Use this for X, use other for Y,' so usage context is only inferred from the name and description.

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?

Even without annotations, the description discloses the stable nature of the URL, free rate-limited pricing, attribution mechanism, and exactly what is returned (canonical URL and x-ref snippet). It clearly implies a non-destructive read operation with no 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 dense but efficient, covering purpose, return values, usage, and pricing in a few sentences without wasted words. Each sentence earns its place, and the key information is front-loaded.

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

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

The description fully covers what the agent needs to know: how to get the URL, what it looks like, how the x-ref works, and the caching guidance. No output schema is provided, so the description effectively explains the return values and usage context.

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

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

The schema has 100% coverage with a description for agentId, so the description does not need to add more. The tool description doesn't elaborate on the parameter, but the existing schema is sufficient, and the description adds no additional parameter-specific meaning.

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 'Get your agent's shareable Flipr referral URL' and goes on to describe both the canonical URL and x-ref snippet, making it distinct from sibling referral tools such as stats, leaderboard, and payout tools.

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 usage context: call once and cache, send the x-ref snippet to another agent verbatim, and notes that the URL is stable. However, it does not explicitly mention when not to use this tool in favor of other referral tools, though the purpose itself implies the alternative.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the payout behavior: manual operator payments, team wallet source, txHash recording via dashboard, the threshold for payout, and the free rate-limited nature. This is highly transparent and exceeds what annotations would typically provide.

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 yet information-dense, with each sentence providing necessary context: purpose, payment mechanics, threshold, status check, and cost. It is well-structured, front-loaded with the primary action, and includes a clear pricing block. 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?

Given the tool's moderate complexity and lack of output schema, the description adequately covers the full workflow: registration, manual payout process, threshold, and status checking. It also addresses potential misconceptions about automated ETH transfers. This is complete for a registration tool with simple parameters.

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 for both parameters (address and agentId). The description does not add extra parameter-level detail beyond what the schema states, but it does contextually reinforce the address's purpose by mentioning 'Register an EVM address.' This meets the baseline of 3 for high schema coverage.

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: 'Register an EVM address for manual referral commission payouts.' This uses a specific verb and resource, and it distinguishes itself from sibling tools by detailing the manual payout mechanism and pointing to the status tool for checking payout status.

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 context on when to use the tool: to register an address for manual referral payouts. It clarifies that the gateway never sends ETH, explains the manual operator process, the 0.05 ETH threshold, and directs users to flipr_referral_payout_status for checking status. This effectively guides the user through the workflow.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses key behaviors: the gateway never sends ETH (manual payout process), the tool is free and rate-limited, and it provides human-readable operator instructions. This goes beyond a generic 'get' description, though it does not discuss data freshness or authentication requirements.

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 plus a pricing tag, front-loaded with the key purpose and return elements. It packs important operational context (manual payout, free/rate-limited) without tangential fluff, though it is slightly dense with enumerations.

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 a single simple parameter and no output schema, the description provides a clear inventory of returned data (commission, eligibility, payoutAddress, last txHash/timestamp, instructions) and crucial context about how payouts work. It lacks an explicit output format, but the logical return components are well-covered.

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 `agentId` parameter, so the schema already documents it as 'Agent identifier to query payout status for'. The description itself does not add parameter-level detail beyond the schema, but it doesn't need to; 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 opens with 'Get accrued referral commission, eligibility for payout..., the registered payoutAddress, the txHash + timestamp...' which identifies a specific verb and explicit resources. This clearly distinguishes it from sibling referral tools like flipr_referral_payout_address (which manages the address) and flipr_referral_stats.

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

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

The description implies the tool's role as a status read, and explains the manual payout context ('The gateway never sends ETH for referrals — operator pays from team wallet'), but does not explicitly state when to use this tool over alternatives like flipr_referral_payout_address or flipr_referral_register. There are no exclusion criteria or named alternative 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?

With no annotations provided, the description carries the full transparency burden. It discloses what is returned, the source of the code, the 2% commission with sticky-after-first-convert behavior, and the FREE/rate-limited pricing. It does not mention side effects like whether registration is persistent or what happens if already registered, but it provides meaningful behavioral context.

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

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

The description is dense and front-loaded with the main purpose. Every sentence adds value (returns, usage incentive, alternative tool, pricing). The embedded pricing JSON is functional but slightly verbose; still, the overall structure is 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?

For a single-parameter registration tool with no output schema, the description is quite complete: it explains what you get, how to use it, the earning model, stickiness, and pricing. It doesn't cover error scenarios or idempotency, but given the simplicity and the sibling pointer, it is adequately complete.

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

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

The single parameter agentId is documented in the schema with 'Your agent identifier', giving 100% schema coverage. The description itself does not elaborate on the parameter, so it adds no value beyond the schema. Baseline 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: 'Register for the Flipr referral program.' It specifies the exact outputs (fliprBetRefCode and share URL) and differentiates itself from the sibling tool flipr_referral_link by calling it a helper for post-registration use.

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

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

The description provides clear context: use this to register and get your referral code, then share it to earn commission. It explicitly points to flipr_referral_link as an alternative for retrieving the share URL. It does not explicitly state when NOT to use this tool, so it misses 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?

With no annotations, the description carries the full burden. It discloses pricing ('FREE') and rate-limiting ('rate-limited only'), which is useful. It also lists return values, but does not mention auth requirements, error behavior, or the read-only nature. There are gaps, but the provided context is adequate for a simple lookup tool.

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

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

The description is a single concise sentence that front-loads the purpose and immediately lists the stats, followed by a compact pricing/rate-limit note. There is zero wasted wording.

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 one-parameter lookup tool with no output schema. The description enumerates exactly what is returned (four stats) and gives the scope ('any agent'). It is fully adequate 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?

Schema description coverage is 100%: the only parameter 'agentId' is documented as 'The agent ID to look up'. The description does not add further meaning about the parameter's format or source, so it adds no value beyond the schema. 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 tool's function: 'Check referral program stats for any agent' and enumerates specific outputs (total volume referred, commission earned, pending payout amount, number of referred agents). This distinguishes it from sibling tools like flipr_referral_leaderboard (which is for leaderboards) and flipr_referral_link (which is for links).

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 use for individual agent referral stats ('any agent') but does not explicitly compare it to alternatives or state when not to use it. It lacks a clear 'use this instead of X' directive, so the usage context is only implied.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool is 'FREE — rate-limited only', adding cost/rate-limit context. The verb 'Get' implies a read operation, but it doesn't explicitly state whether there are side effects or what the response format is. This is adequate but not comprehensive.

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: two sentences that state purpose and usage, followed by pricing metadata. It is front-loaded with the main purpose. The appended pricing JSON is a bit clunky but not overly verbose, making the overall length appropriate.

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 has no parameters and no output schema, the description provides a good list of what the status includes (treasury address, latencies, agent count) and notes rate limiting. It lacks explicit return format details, but for a simple read-only status tool, the description covers the essential context for an agent to decide to invoke it.

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 there are no parameters to describe. The baseline for 0 params is 4, and the description does not need to add parameter details. No additional semantics are required.

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 'Get detailed gateway status' with specific content fields (treasury address, subsystem latencies, agent count), using a specific verb and resource. It also distinguishes from siblings by positioning itself as 'beyond basic health checks', which clearly differentiates it from flipr_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?

The description provides clear usage guidance: 'Use for deeper diagnostics beyond basic health checks.' This implies when to use the tool (when more detail is needed) and contrasts with basic health checks, likely referring to a sibling tool. It does not explicitly name the alternative but gives sufficient context.

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

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

With no annotations, the description bears full responsibility for disclosing side effects. It reveals the cost, payment networks, and auto-bridging, but fails to mention that the withdrawal is irreversible (funds are moved out) and contradicts itself by saying ETH while the schema says USDC. The missing permanence and internal inconsistency undermine trust.

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 purpose and return, then includes important usage notes, cost, and a link. The trailing metadata blocks ([paymentNetworks], [pricing]) add noise but do not excessively inflate the size. It earns a 4 for efficiency.

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 core function, return value, cost, payment networks, and provides a link for further details. Missing are explicit statements about irreversibility, minimum balance, or failure modes. The currency inconsistency reduces completeness. Overall, adequate but with gaps.

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

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

Schema coverage is 100% with clear descriptions for both parameters, so baseline is 3. The description adds little beyond calling the destination 'a specified address' and introduces a currency conflict (ETH vs USDC) that could mislead the agent about parameter usage.

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

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

The description clearly states the action (withdraw accumulated ETH from Flipr agent wallet to a specified address) and mentions the return (transaction hash). It distinguishes from siblings as no other tool handles withdrawals. However, the inconsistency between 'ETH' in the description and 'USDC' in the input schema introduces ambiguity about the actual asset withdrawn.

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: 'Only call this when you want to cash out' and warns that ETH in the agent wallet is needed for future flips. This provides clear usage guidance and a reason to avoid unnecessary use, even though no alternative tool is mentioned.

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