walletlink.social

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

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context: it is free on both meters, remains available when credits are drained, and clarifies that rate_limit_units_used is not a credit figure. This goes well beyond the annotation hints and prevents misinterpretation.

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, leading with the core purpose, then cost and usage context, then a precise clarification of the two returned fields. Every sentence earns its place without repetition 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?

Despite having no output schema, the description fully explains the tool's return values, cost behavior, and operational semantics at zero balance. An agent has enough context to invoke the tool and interpret its results 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 takes no parameters, so there are no parameter semantics to document. The description instead explains the meaning of the returned values, which is the appropriate compensation for having no output 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 what the tool reports: remaining match credits and request allowance usage for the configured key. It distinguishes the tool from sibling tools by focusing on account meters rather than lookup or coverage 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 gives explicit usage guidance: 'Call it before a reverse lookup, which can spend up to 100 credits in one go.' It also explains what happens when the meter hits zero—resolve and reverse tools refuse while this tool and the coverage tool keep working—so an agent knows when this tool remains available.

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 mark read-only and idempotent, but the description goes further: it discloses that counts only are returned (no identities), that it is always free on the match meter, and that the rate window weighs exactly like a real resolve. It also explains the 'band' semantics, adding valuable behavioral context beyond 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?

Description is fairly long but every sentence contributes meaning: cost, rate window, constraints, band interpretation, cross-chain caveat. The prose is tightly packed and organized in digestible paragraphs; the only minor issue is that some phrasing ('the band a resolve would bill inside') is dense enough to require rereading.

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 fully compensates: it explains what counts are returned, how to interpret the high/low band, the cost model, and the minimum/ceiling constraints. An agent can select and invoke this tool correctly with no further reference.

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 only parameter, addresses, is fully described in the schema (format, min/max). The description adds nuance by specifying 'distinct addresses' and tying minimum count to aggregate-by-design behavior, giving practical validation guidance 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 begins with 'A dry run over a list of addresses' followed by explicit output counts, clearly distinguishing it from spending/consuming operations. It names the decision purpose 'decide whether a list is worth resolving, and which tool to spend on', making the tool's unique role unmistakable.

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 use ('Use it to decide whether a list is worth resolving') and points to alternatives: the coverage tool and /v1/stats for per-chain match rates. Also lists constraints (minimum 10 addresses, batch ceiling) and cost behavior, leaving no ambiguity about appropriate invocation.

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 and idempotentHint, and the description adds significant behavioral detail: it resolves no wallet, is free on both meters, consumes no rate limit, works even with zero balance, counts are refreshed daily, and as_of indicates when they were taken. This far exceeds the annotation coverage and fully explains the tool's side effects and 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 structured: purpose front-loaded, then cost details, then explanation of the numbers. It is a bit verbose with the cost paragraph, but every sentence adds value whether clarifying cost, data freshness, or interpretation. It is not overly long for the information provided.

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?

Without an output schema, the description carries the burden of explaining what the tool returns. It does so clearly: the two numbers, their relationship, the larger share for bare addresses, the refresh cadence, and the as_of field. An agent has everything needed to interpret the result and decide on subsequent actions.

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 no parameters, so the description cannot add parameter specifics. The baseline for zero params is 4, and the description compensates by explaining the response fields (addresses_with_an_identity, addresses_checked, as_of) and their meaning, which is more than expected.

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 does: reports how much of the index carries each identity type, and context for evaluating whether a lookup is worthwhile. It clearly distinguishes this from sibling tools (which resolve wallets or check balances) by focusing on coverage statistics.

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 to use this tool before making a lookup to judge if it's worth it. It also notes the tool is free and consumes no rate limit, guiding when to call it. It does not explicitly name alternative tools for when not to use it, but the purpose and cost context make usage 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 adds substantial behavioral detail beyond the readOnly and idempotent annotations: cost is free on both meters, absent fields mean 'not measured' rather than false, and foreign job IDs return not found. This meaningfully helps an agent interpret results and avoid incorrect conclusions.

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 provides essential caveats in a compact structure. Every sentence adds value, from cost behavior to absent-field semantics to account scoping, without filler or repetition.

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

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

The tool has no output schema, so the description carries the burden of explaining results: progress counts, completed results, billing, cost implications, absent-field semantics, and authorization limits. This is sufficient for an agent to call the tool correctly and interpret its response.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics for job_id by explaining ownership and not-found behavior, which helps an agent reason about invalid or foreign IDs. It does not add offset detail, but the schema already covers that fully.

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 reports progress and results for a specific background job and ties it to walletlink_submit_job. It distinguishes the tool from sibling walletlink operations by naming the job-oriented counterpart and scoping visibility to jobs submitted by the current account.

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 establishes the intended context: it is for jobs previously submitted with walletlink_submit_job, and it explicitly warns that only this account's jobs are visible. It does not name explicit exclusions or alternatives, but siblings make the role obvious and the constraints are 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?

Annotations only declare readOnlyHint=true and idempotentHint=false. The description adds extensive behavioral detail: billing rules per identity type, quota ceilings by plan, BATCH_SIZE_EXCEEDED error, duplicate handling inside a call, retry re-billing, attestation status, and suspended handles. No contradiction with 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?

Though long, every sentence carries operational value. The text is organized into focused paragraphs: function, cost, result semantics, batching, retry behavior. The structure is front-loaded with the core purpose and follows with necessary caveats. No fluff or repetition.

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

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

The description fully covers what an agent needs: input constraints, output semantics (attested vs correlated, suspended handles), cost model, rate limits, and retry implications. There is no output schema, so the description's mention of per-identity attestation and handle reachability compensates for that. Nothing critical 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 is 100%, so the format, pattern, and min/max items are already documented. The description adds meaningful parameter-related context: duplicates are removed before charging, each copy costs throughput, and address count affects request-unit usage. This goes beyond the raw schema and helps the agent properly size the 'addresses' array.

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 starts with a specific verb ('Resolve'), identifies the resource ('one or more Ethereum addresses') and the result ('social identities attached to them: X handle, Farcaster account, ENS name, Lens profile, GitHub account'). It clearly distinguishes from sibling tools like walletlink_account_balance or walletlink_wallets_by_x_handle by focusing on address-to-identity resolution.

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 explicit usage context: send all addresses in one call, pace multi-batch runs a minute apart, read the reset time from the quota, and avoid blind retries. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is strong enough that an agent knows when this tool fits. Minor gap: no direct contrast with sibling tools like walletlink_wallets_by_x_handle.

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 carry shallow flags (readOnly=false, idempotent=false, destructive=false). The description adds substantial behavioral detail: billing on matches, free misses, one active job per account, refusal behavior naming the active job id, the 10x balance cap, request-unit cost, polling flow, no billing on failure, and resubmission re-running and re-billing.

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

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

The description is longer than average but every sentence earns its place: core purpose first, comparison to the alternative, explicit usage condition, cost and limits, return behavior, and resubmission warning. The structure is scannable with clear paragraphing.

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?

Despite no output schema, the description explains what the submission returns (a job id), how to retrieve results (poll job_status), the cost model, failure handling, concurrency limit, and resubmission semantics. Nothing an agent needs to call this asynchronous tool correctly 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 is 100% and already documents the address format and balance-derived cap. The description adds the exact 10x multiplier, the active-job limitation, and notes that case does not matter, going slightly beyond the schema without being duplicative.

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 and resource: 'Submit a list of addresses as a background job.' It clearly distinguishes this from the resolve tool by explaining that a job performs a deeper scan against live sources, and it also names the polling sibling (walletlink_job_status) for results.

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?

Explicit guidance is provided: 'Use it for lists larger than one resolve call, or when misses are worth re-checking.' This directly tells an agent when to choose this tool over the resolve tool and implies the alternative for lighter or single lookups.

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

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

Beyond the readOnlyHint annotation, the description discloses significant behavior: one match credit per wallet returned, empty results are free, retried calls bill again, page size up to 100, and follower-count ordering. This directly informs cost-sensitive agent decisions and is not redundant with 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 compact and front-loaded: purpose first, then cost, edge behavior, and ordering. Every sentence contributes actionable information 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?

The tool is moderately complex due to billing and pagination, and the description covers cost, empty results, retries, suffix handling, and ordering. It omits explicit response field details, but with no output schema and a simple wallet-list result, the missing return-shape detail is minor.

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 schema already documents parameters. The description adds important semantic guidance for the username parameter by warning that stripping .eth will find nothing, which goes beyond the bare pattern and example in 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 opens with a specific action and resource: 'Find every wallet in the index attested to a Farcaster account.' This clearly distinguishes the tool from sibling 'walletlink_wallets_by_x_handle' by naming the Farcaster domain.

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 operational context: pass the username whole, include any .eth suffix, and expect results ordered by follower count. It does not explicitly name sibling alternatives or state when not to use this tool, but the Farcaster-specific scope makes the intended use obvious.

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 provide readOnlyHint true and idempotentHint false, but the description goes far beyond by detailing cost per wallet, page size, free allowance, ordering by Farcaster follower count, and the billing behavior of retried calls. This adds significant operational context beyond 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 organized into purpose, cost, and results/ordering sections. Every sentence earns its place, though the cost section is slightly verbose. Front-loaded purpose makes it 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 tool with only 2 parameters and no output schema, it covers purpose, cost, pagination, and ordering. It does not explicitly describe the response shape (list of wallet objects) beyond mentioning more_pages and ordering, but the absence of an output schema makes that a minor gap.

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, each fully described with patterns and usage notes. The description adds general pagination context (more_pages, next_cursor) but not new parameter-level specifics, so baseline 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?

Clearly states 'Find every wallet in the index attested to an X account' with a specific verb and resource, and adds 'The reverse of resolving an address' to distinguish it from the forward direction. This differentiates from siblings like walletlink_resolve_wallets.

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 tells when to check balance first with walletlink_account_balance, warns about cost on retries, and provides pagination instructions with 'pass next_cursor back'. It also describes the empty-list case for unheld handles, giving clear decision context.

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