walletlink.social

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 covered. The description adds substantial behavioral context beyond annotations: the cost is free on both meters, matches_available is the meter that stops metered calls, rate_limit_units_used is a separate request count not a credit figure, and unmetered accounts have null matches_available. This explains edge-case behavior (null vs zero) that an agent needs to interpret the response correctly.

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 well-structured and front-loaded: the first sentence states the core purpose, the second gives cost and usage guidance, and the following sentences explain the two meters and the unmetered edge case. Every sentence earns its place, and the structure moves from high-level purpose to specific behavioral details without redundancy.

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

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

For a zero-parameter, read-only tool with no output schema, the description is complete. It explains what the tool returns, how to interpret the two key fields, the cost implications, and the edge case for unmetered accounts. An agent has everything it needs to call the tool and interpret the result correctly. The absence of an output schema is compensated by the description's explanation of the return fields.

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 schema provides no parameter semantics to clarify. The description compensates by explaining the meaning of the two key output fields (matches_available and rate_limit_units_used), which is the closest analog to parameter semantics for a no-input tool. Baseline 4 is appropriate for zero-parameter tools, and the description adds value by defining the output 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 the tool's purpose: reporting how many match credits the configured key has left and how much of the request allowance it has used. It names the specific resources (matches_available and rate_limit_units_used) and distinguishes itself from sibling tools by explaining it is a read-only meter tool, unlike resolve/reverse tools that spend credits.

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 when to use this tool: 'Call it before a reverse lookup, which can spend up to 100 credits in one go.' It also explains when the tool remains useful (when a key is drained, this tool and coverage tool keep answering), providing clear context for choosing it over alternatives. It doesn't name a specific sibling alternative, but the usage context is explicit 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?

Even though annotations already mark readOnlyHint=true, idempotentHint=true, and openWorldHint=false, the description adds substantial behavioral context: it is always free on the match meter even at zero balance, it consumes one request-unit per address, it requires a minimum of 10 distinct addresses due to aggregate design, and it explains exactly what low vs. high bands mean. This goes well 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 front-loaded with the tool's purpose and safety profile ('dry run', 'counts only'), then structured into cost, batch constraints, and band semantics. Every sentence contributes necessary decision-making information, and the prose is dense without being padded.

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

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

With no output schema present, the description does the work of explaining what the tool returns: counts in each category and the billing band, plus the low/high band interpretation. It also covers cost, rate-window behavior, minimum/ceiling batch sizes, and where to get per-chain matching rates, so an agent has what it needs to call the tool and interpret the result.

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 documents the address format, minItems, and maxItems at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the 10-address minimum is about distinct addresses, explaining the per-address request-unit cost, and mentioning the plan's batch ceiling. It slightly falls short of 5 because duplicate-address handling is implied but not fully explicit.

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 concrete operation ('dry run over a list of addresses') and the resource (address list estimate) with a specific outcome: counts of indexed, checked-bare, never-seen addresses plus a billing band. It differentiates itself from the resolving sibling by saying 'Counts only, no identities' and 'Use it to decide whether a list is worth resolving,' so an agent can distinguish it 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?

The description explicitly states when to use the tool: 'Use it to decide whether a list is worth resolving, and which tool to spend on.' It contrasts the low band with a real resolve and the high band with background resolves, and points to the coverage tool and /v1/stats for per-chain rate tables. This gives clear decision context relative to sibling 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 adds substantial behavioral detail beyond the annotations: it is free on both meters, resolves no wallet, consumes no rate limit, works even with zero balance, and returns daily-refreshed counts rather than live data. It also explains the coverage rate formula and why the second number is larger. The 'asking twice in a day returns the same numbers' detail aligns with the idempotentHint annotation.

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

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

The description is appropriately sized for a simple no-parameter tool. Every sentence earns its place: purpose, cost/rate-limit behavior, and interpretation of the returned numbers are all covered without redundancy. The purpose is front-loaded, and the explanation of the coverage rate is clear.

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 and strong annotations, the description is complete. It covers what the tool measures, how to use it, what the numbers mean, freshness behavior, and cost/rate-limit implications. An agent has everything needed to decide whether to call it and how to interpret the result.

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 schema coverage is trivially 100%, so the baseline for parameter semantics is 4. The description does not need to explain parameters, and instead clarifies the meaning of the returned fields (addresses_with_an_identity, addresses_checked, as_of), adding value 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 states exactly what the tool reports ('How much of the index carries each identity type') and its purpose ('judge whether a lookup is worth making before making it'). This clearly distinguishes it from sibling tools like resolve_wallets or account_balance, which perform actual lookups or balance reads.

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 when to use it: before making a lookup, to judge whether the lookup is worthwhile. It also provides practical context about cost and rate limits. It does not explicitly discuss when not to use it or name alternatives, but the usage context is clear.

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 by explaining free metering even for drained keys, the ownership restriction, and the critical semantics that an absent field means 'not measured' rather than false or negative. These are non-obvious behavioral traits that materially affect how an agent should interpret results.

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: the core purpose appears in the first sentence, followed by cost, missing-field semantics, and visibility constraints. Every sentence earns its place, and the caveats are essential rather than 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?

With no output schema, the description does the work of explaining return semantics: processed counts, resolved records, billing, and absent-field meaning. It is highly informative, but it does not address failure/error states or terminal job status values, which would make it fully complete for a job-status tool without an 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?

The schema already documents both parameters with 100% coverage, including the UUID format and offset continuation semantics. The description adds no additional parameter-level detail, so the baseline 3 is appropriate because the schema carries the burden.

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

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

The description states a specific verb and resource: it reports progress and results for a job previously submitted via walletlink_submit_job. It clearly differentiates this from sibling tools by anchoring it to the submission workflow, and the first sentence makes the tool's scope immediately obvious.

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 clear context for when to use the tool: it is the status/result companion to walletlink_submit_job, and it explicitly notes that only jobs submitted by this account are visible, so other IDs will return not found. It lacks an explicit 'use this instead of X' statement, but the context is sufficient to route an agent correctly.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses credit costs, batch limits, duplicate removal and charging, retry billing, and the distinction between attested and correlated identities. It also warns about retries without idempotency keys – far more transparent than the annotations alone.

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 every section (purpose, cost, limits, duplicates, retry) is purposeful and adds value. It is front-loaded with the core function and then provides necessary operational details without filler. Slightly long but justified by complexity.

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 purpose, cost, limits, batching, duplicate handling, idempotency, and result characteristics (attestation, X handle status). Given there is no output schema, it gives enough insight into the response. It is comprehensive 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 schema already covers the address format, but the description adds crucial semantics: send all addresses in one call, duplicates are removed before charging but still cost throughput, and ceiling limits per plan (50/200/1000). This significantly enriches understanding of the 'addresses' parameter.

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 'Resolve one or more Ethereum addresses to the social identities attached to them' – a specific verb, resource, and outcome. It lists the identity types (X, Farcaster, ENS, Lens, GitHub) and clearly distinguishes this forward lookup from sibling tools like walletlink_wallets_by_x_handle (reverse lookup).

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 detailed operational guidance: batching, credit costs, plan ceilings, pacing, and retry behavior. However, it does not explicitly mention alternatives or when-not-to-use this tool versus siblings, so it falls short of a 5.

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

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

Annotations only hint that this is not read-only, not idempotent, and open-world. The description adds substantial operational behavior: billing on matches, misses free, one active job per account, cap at 10x match balance, refusal behavior, failure never billed, and resubmission rerunning and rebilling. This goes well beyond what annotations 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 long but every sentence carries necessary operational information: cost, concurrency, cap, failure handling, polling, and resubmission behavior. It is front-loaded with the core purpose and then organized into clear paragraphs.

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, but the description states the return value is a job id and directs the agent to poll walletlink_job_status for progress and results. It also covers billing, failure, the active-job limit, and resubmission consequences, so an agent has the essential constraints needed to call this 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 input schema already fully describes the addresses parameter: format, minItems, and the balance-derived cap. The description only restates that a list of addresses is submitted and does not add new parameter-level semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource: submitting a list of addresses as a background job. It also clearly differentiates itself from the resolve tool by explaining the deeper scan and that it can find identities resolve reports as never seen.

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 use conditions: lists larger than one resolve call, or when misses are worth re-checking. It also names the polling path via walletlink_job_status and warns about the one-active-job constraint, so an agent knows when submission will be refused.

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 are minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the burden. It discloses cost per wallet, billing on retries, free empty results, filtering logic, and the ACCOUNT_REQUIRED error. This goes well beyond annotations and gives the agent a clear picture of side effects 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 dense but every sentence earns its place. It front-loads the core purpose, then explains filtering, cost, and usage tips in a logical order. No fluff or repetition. The structure aids comprehension despite its length.

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 usage, cost, filtering, pagination, and error conditions comprehensively. However, since there is no output schema, it does not describe the return format (e.g., wallet object structure). For a list tool, this is a notable omission, but the description still gives enough for an agent to call it correctly and interpret results at a high level.

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 value beyond the schema by explaining the .eth suffix pitfall ('stripping the suffix will find nothing') and the cost implications of pagination. It also clarifies the cursor's role in the context of billing. This extra context justifies a 4.

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

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

The description clearly states the tool's function: 'Find the wallets in the index attested to a Farcaster account.' It specifies the resource (wallets), the scope (attested to a Farcaster account), and adds precise filtering behavior (only wallets whose recorded sources are all attested). This distinguishes it from sibling tools like walletlink_wallets_by_x_handle, which target a different identity type.

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: how to pass the username (including .eth suffix), prerequisites (key belonging to an account), and pagination (omit cursor for first page). It also explains cost implications and error conditions (ACCOUNT_REQUIRED). However, it does not explicitly state when to use this tool over alternatives like walletlink_wallets_by_x_handle, though the name implies the distinction.

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 richly discloses behavior beyond annotations: only fully-attested wallets are returned, correlated-source wallets are excluded, auth requirements exist, USDC-only keys fail, each returned wallet costs a match credit, retried calls are billed again, results are ordered by Farcaster follower count, and pagination uses more_pages and next_cursor.

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 long but every sentence carries a distinct operational fact: purpose, exclusions, auth failure, cost, retry billing, ordering, and pagination. It is front-loaded with the core behavior and keeps supporting details in clearly separated blocks 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?

For a tool with no output schema, the description covers auth, failure modes, pricing, empty results, ordering, and pagination. The only minor gap is that it does not spell out the exact shape of returned wallet objects, though the tool's purpose and sibling context make this less critical.

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%, with handle and cursor already fully documented. The description adds runtime context around cursor continuation and cost implications, but it does not add substantial new per-parameter meaning 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?

The description states a specific action and resource: finding wallets in the index attested to an X account. It also explicitly frames itself as the reverse of resolving an address, which distinguishes it from the sibling resolve_wallets tool without ambiguity.

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 clearly explains this is the inverse of address resolution, giving an agent context for when to use it versus resolving an address. It also gives a concrete precondition around account-key ownership and the ACCOUNT_REQUIRED error. However, it does not explicitly compare itself to walletlink_wallets_by_farcaster_username, the closest sibling alternative.

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