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.