Mekler AI

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

Adds substantial context beyond the annotations: the return is a 90-day listing-control credential, retries are idempotent in a specific way (the grant is recovered), and a new proof revokes prior credentials. It also bounds scope negatively ('does not approve branding or change grades', 'never signs payments'), which is exactly the kind of side-effect disclosure a mutation tool needs.

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?

Five short sentences, front-loaded with the action and its precondition, followed by return value, idempotency, side effects, and negative scope. No sentence is filler; each carries a distinct fact an agent needs.

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 covers the return value, its lifetime, retry behavior, destructive side effects on prior credentials, and explicit non-effects. Nothing an agent needs in order to invoke this 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 description coverage is 0%, so the description must carry the semantic load. It adds real meaning for requester_key ('the same private requester key', i.e. must match the start call) and situates challenge_id as a one-hour domain challenge, but adds nothing about formats or failure conditions for either 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?

States a specific verb and resource ('Confirm a one-hour domain challenge') with the key constraint that makes it work. The verb naturally distinguishes it from the sibling start_ownership_proof, but the description never names that sibling explicitly, so the differentiation is implicit rather than stated.

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

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

Gives clear operating context: the requester key must be the same private key, and the HTTPS origin and path must match exactly. The retry semantics ('identical retries recover that grant') clarify re-invocation behavior. It does not explicitly state the prerequisite call (start_ownership_proof) or name alternatives, so it stops 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?

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing the exact cost (0.25 USDC on Base or Solana), the return encoding (gzip+base64 JSON plus digest), the 60-second signed download URL for large results, and the 30-day result-recovery behavior. The 'Never signs payments' clause usefully clarifies that the caller must supply proof, and it is consistent with the idempotentHint.

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

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

Four dense sentences, front-loaded with scope and result format, then payment cost, then recovery semantics. No filler; each sentence adds operational information.

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?

No output schema exists, yet the description fully covers the return shape (gzip+base64 JSON, digest, signed URL), payment/auth requirements, idempotency-based recovery, and the truncation cap. An agent has everything needed to call and interpret 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?

Schema coverage is 0%, so the description must carry the parameter burden. 'Reuse the original body and payment proof for exact 30 day result recovery' gives real meaning to idempotency_key and payment_signature, but it never explains the key format, length constraints, or the distinction between the two parameters, leaving gaps the schema cannot fill.

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 (export) and resource (visible scanned x402 services), and enumerates exactly what is included: grade history, first seen, scan counts, provenance and explicit truncation. This clearly separates it from siblings like search_listings and retrieve_listing, which are retrieval rather than bulk export.

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 usage context (bulk export up to 10000 records, truncation handling, paid operation) but never explicitly states when to choose this over search_listings or retrieve_listing, nor any prerequisites beyond payment. Usage is inferable but not routed.

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. The description adds two genuinely behavioral facts: a 24-hour expiry (a failure mode the agent must plan around) and that the call never purchases a replacement (cost/authorization behavior). Missing is what happens on an expired or unknown id.

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

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

Two short sentences, the core action front-loaded, and the expiry constraint placed immediately after. Every clause carries information; nothing is padding.

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 read with no output schema, the description covers purpose, lifetime constraint, and cost behavior. It could say a bit more about error behavior on expiry or what the report contains, but it is largely sufficient.

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?

One parameter with 0% schema description coverage, so the description must carry it. 'By report_id' identifies the parameter's role but adds no format, length, or expected-value information beyond the self-evident name.

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 (read) and a precisely scoped resource (a completed public cached report) keyed by report_id. The qualifiers 'completed' and 'cached' distinguish it from the sibling get_scan_status, though no sibling is named explicitly.

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?

'Completed' implies you should only call this once a scan has finished, and 'never purchases a replacement' implies this is not the tool for obtaining a fresh report. Both are inferred rather than stated, and no alternative tool is named for that case.

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?

readOnlyHint=true already declares the non-mutating profile, and the description usefully reinforces it by stating that polling neither starts work nor settles payment. It adds no detail on what job states can be returned, error conditions, or how recovery_capability affects behavior, so it goes only slightly beyond the 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?

Two short sentences, front-loaded with the purpose and followed by the key polling guarantee. No 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?

There is no output schema, so the description should at least sketch what the job state contains and what values it can take, plus what recovery_capability is for. Neither the return shape nor the parameter meaning is covered, leaving a polling tool materially under-described.

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 0% for both required parameters. The description only restates their names ('with job_id and recovery_capability') without explaining format, origin, or the unusual semantics of recovery_capability, so it fails to compensate for the coverage gap.

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 ('Read a conformance job state'), which is clear on its own. It does not distinguish itself from sibling get_scan_report or list_conformance_checks, so an agent must infer the boundary between reading status and reading a report.

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

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

The phrase 'Polling never starts work or settles payment' implies this tool is the intended polling endpoint and is safe to call repeatedly, which is useful implied guidance. It never explicitly says when to use this versus get_scan_report, nor does it state prerequisites for obtaining a job_id or recovery_capability.

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 behavioral burden and does not meet it. It discloses only that the returned contract is 'complete'; it says nothing about authentication requirements, what happens when the identifier is not found, or what the referral_code parameter does behaviorally.

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

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

A single sentence, front-loaded with the verb and resource, with the identifier forms appended economically. 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 annotations, no output schema, and one of two parameters undocumented, the description is under-specified. It omits referral_code semantics, error/not-found behavior, and any access requirements an agent needs to call it correctly.

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

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

Schema coverage is 0%, so the description must compensate. It usefully clarifies that 'id' accepts slug, operation ID, name, or endpoint URL — information the bare string schema lacks — but leaves referral_code (a 22–64 character string) entirely unexplained, so only half the parameters gain 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?

States a specific verb ('Get') and resource ('complete public service or operation contract') and enumerates the four lookup keys. It is distinguishable from search_services in intent (retrieve one full contract vs. search), but the description never names or contrasts that sibling explicitly.

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 list of accepted identifiers (slug, operation ID, name, endpoint URL) implies how to invoke it, but there is no statement of when to prefer this over search_services, no prerequisites, and no guidance on which identifier form to choose.

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 readOnlyHint=true already declaring a safe read, the description still adds useful context: it is free, requires no wallet funds or payment, and mentions wallet-auth instructions. It does not state what 'operation' does or what is returned, and the phrase 'First signed execution enrolls automatically' describes a side effect downstream of this call, which sits awkwardly beside a read-only 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?

Two short, front-loaded sentences with no filler; the core read action comes first and the enrollment/free-of-charge caveat follows. Efficient for the little it says.

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, no annotations beyond readOnlyHint, and a fully undocumented required parameter, the definition leaves major gaps: the agent does not know valid 'operation' values or the shape of the returned service request/auth instructions.

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 0% and the single required 'operation' string parameter has no enum, no description, and no examples. The description never explains what values 'operation' accepts, so the agent has no way to populate the only required parameter from the definition.

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 verb+resource ('Get the service request and standard wallet-auth instructions'), so the general purpose is discernible. However, 'service request' is vague and it never differentiates itself from siblings like get_service, get_trial_offer, or rotate_trial, leaving the agent to guess which trial-related tool to call.

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 implies a first-time onboarding context ('First signed execution enrolls automatically'), but gives no explicit when-to-use or when-not-to-use guidance and never names an alternative among the four trial/service siblings.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description is consistent with that ('Read'). It adds some scope context by enumerating the topics covered (offer, wallet authentication, allowance, paid transition), but gives no detail on output shape, freshness, or whether it is scoped to a caller's wallet. With annotations covering the safety profile, this is a modest contribution.

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

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

A single sentence that leads with the verb and wastes no preamble. The compressed noun list makes it denser than it needs to be and hurts readability, but there is no filler text.

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

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

With no output schema and no parameters, the description carries the full burden of explaining what comes back, and it does not: 'offer, wallet authentication, allowance and explicit paid transition' names domains but not the returned structure or fields. Adequate to identify the tool, incomplete for an agent that must reason about 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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level confusion is possible.

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 verb 'Read' plus resource 'trial offer' is identifiable, but the object of the read is delivered as a stacked noun list ('adjustable free-use offer, wallet authentication, allowance and explicit paid transition') that never resolves into a clear statement of what is returned. It also fails to distinguish itself from the sibling get_trial_access, leaving the boundary between the two ambiguous.

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?

There is no indication of when to call this rather than get_trial_access, rotate_trial, or get_service, and no stated preconditions or context. The description offers no routing guidance whatsoever.

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?

readOnlyHint=true already establishes this is a safe read, so the description only needs to add context. It does add a little — the catalogs are 'versioned' and there is defined 'unknown-evidence semantics' — but says nothing about output shape, catalog size, or how the two catalogs relate. Adequate but thin against the lower bar set by 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?

A single front-loaded sentence with no filler; the verb and resources come first. It is jargon-heavy ('unknown-evidence semantics'), which costs a little clarity but nothing is wasted.

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

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

With no parameters and no output schema, the description should ideally convey what an agent gets back (a list of check identifiers with grading rules, etc.). It names the content domains but never describes the return form, so an agent cannot predict the response structure.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There are no arguments whose semantics could be misunderstood.

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 gives a concrete verb (Read) and names the resources: a versioned 25-check linter catalog, a separate 14-check compliance catalog, plus grading rules and unknown-evidence semantics. That is more than a restatement of the name 'list_conformance_checks'. Sibling tools (scan, referral, trial, service) are unrelated, so no differentiation is needed, but the dense phrasing leaves it slightly ambiguous whether it returns the checks themselves or the catalog metadata.

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?

There is no statement of when to call this versus alternatives, no prerequisites, and no exclusions. The siblings are in unrelated domains, so the omission is less costly, but the description offers no usage context at all.

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 only readOnlyHint=false and idempotentHint=true in annotations, the description carries the load and does so richly: pagination defaults (200/1000), signed watermark cursors, retention limits (30 days or 50000 events), the 410 response on expired cursors, per-page cost (0.01 USDC on Base or Solana), and the explicit 'Never signs payments' constraint. These are exactly the operational facts an agent needs beyond the annotation surface.

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 purpose is front-loaded in the first sentence and each subsequent clause delivers a distinct fact (pagination, retention, cost, idempotency, recovery, payment). It is dense and somewhat telegraphic, but no sentence is 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 payment-gated paginated read tool with no output schema, the description covers pagination, retention, error behavior, cost, and idempotency well. What is left thin is the exact shape of the returned grade/score events, which an agent would still have to discover at runtime.

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 0%, so the description must compensate. It does explain limit (default 200, max 1000), cursor (signed watermark), and idempotency_key usage, but payment_signature's role is only obliquely implied by the cost and 'Never signs payments' lines rather than stated. Three of four parameters are meaningfully covered, leaving a real gap.

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: 'Read ordered new, grade_changed and rescanned events with previous grades and scores.' That is far more precise than a restated name and lets an agent know exactly what domain of data is returned. It stops short of naming any sibling or explaining why it differs from the listing/scan/referral tools, so it does not fully earn 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?

It gives procedural guidance ('use a fresh idempotency key per page', 'retain the original body and proof for exact recovery') but never states when to reach for this tool versus an alternative, nor any preconditions for calling it. With no close sibling in the set, usage is only implied by the resource 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?

readOnlyHint=false already tells the agent this is a write, and the description adds meaning beyond that: the SIWx challenge/signature auth requirement, that signing must use the referrer wallet, and the reassurance that no payment is authorized. It omits rate limits, idempotency, and side effects of accepting a version.

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?

Front-loaded with the action and its payoff, then the argument source, then the calling sequence; every sentence carries information. It is dense and slightly clipped (the 'arguments:' fragment), but there is 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 nested-object tool with no output schema and 0% parameter coverage, the description covers the challenge/response flow and the no-payment caveat well but leaves new_proof and the object shapes unexplained, so an agent could still mis-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?

Schema description coverage is 0% for three object parameters, so the description must compensate. It explains that arguments carries terms_version and terms_digest from referral_program, and implies proof is the signed challenge, but new_proof is never explained and the structure of these objects is left undocumented.

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 (accept a newer version of the referral terms) plus the motive (to keep earning), which is far beyond a restatement of the name. It references referral_program as the source of terms_version/terms_digest, giving useful lineage, though it does not explicitly distinguish itself from sibling tools like referral_acknowledge.

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

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

Gives an explicit two-step calling procedure: call without proof to obtain a SIWx challenge, sign it with the referrer wallet, then call again with proof. This is strong how-to guidance, but it never states when to prefer this tool over siblings such as referral_acknowledge or referral_register.

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?

readOnlyHint=false is consistent with a mark-as-read mutation, and the description goes beyond the annotation by disclosing the two-phase SIWx authentication requirement and stating 'No payment is authorized,' which prevents an agent from assuming a cost. It omits idempotency, cursor-staleness behavior, and error outcomes.

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?

Three front-loaded sentences with no filler, and the sequencing instructions appear in call order. Slightly dense with three distinct ideas packed without visual separation, but nothing is wasted.

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 nested-object, zero-coverage, no-output-schema tool, the description covers the auth flow and cursor semantics adequately but leaves new_proof, required-vs-optional status of proof/arguments, idempotency, and cursor-overrun behavior unspecified.

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 0% across proof, arguments, and new_proof, so the description must carry the load. It does map 'arguments: cursor (integer) and optional private_cursor' and ties proof to the challenge flow, but leaves new_proof entirely unexplained and gives no format detail for the proof object.

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?

Specific verb+resource ('Mark notices already served by referral_notices as read up to a cursor') and it explicitly anchors the resource to the sibling tool that produced it, so the agent can separate acknowledge from notices without opening a schema.

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 gives the exact two-call flow: call without proof to obtain a SIWx challenge, sign with the referrer wallet, then call again with proof. That is strong operational context, though it never states when not to use this tool or what happens if the flow is abandoned.

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=false. The description goes further, disclosing the required signing handshake with the referrer wallet, the distinction between published notices and private account events, and the notable constraint that no payment is authorized. It does not cover pagination behavior or what the challenge expires around.

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?

Front-loads the verb and resources, then packs parameter contents and the auth flow into two dense sentences with no filler. The closing payment disclaimer is short and earns its place by pre-empting confusion with the proof/sign flow, though the sentence reads slightly clipped.

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 three-parameter, nested-object tool with no output schema and a non-obvious two-call auth handshake, the description covers the flow and the arguments sub-object but omits any explanation of new_proof and gives only a one-line sketch of return contents. Adequate to attempt a call, not complete enough to do it confidently in one pass.

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 0% and the three top-level parameters (proof, arguments, new_proof) are nested objects with no documentation. The description exposes the internals of arguments (optional cursor, limit 1-50, private_cursor) and implies what proof is via the flow, but says nothing at all about new_proof, leaving a documented gap.

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 two concrete resources: published program notices plus the referrer's private account events. That is well beyond a restatement of the name, and it separates it in spirit from sibling reads like referral_status or referral_receipts, though it never names a sibling explicitly.

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

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

Gives an explicit operational procedure: call without proof to obtain a SIWx challenge, sign it with the referrer wallet, then call again with proof. That is clear context for invoking it, but there is no when-to-choose guidance relative to the many other referral_* siblings.

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?

readOnlyHint=true is consistent with 'Read', so no contradiction. The description adds useful content scope (availability, terms, commission offer), which goes beyond the annotation, but says nothing about caching, freshness, or what an unregistered/eligible-vs-not result means.

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

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

A single front-loaded sentence with no waste. The resource and payload are stated immediately.

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

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

With no parameters, no output schema, and a readOnly annotation, this is close to sufficient: it tells the agent what information comes back. Minor gap is the missing relationship to sibling referral_* reads.

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?

Zero input parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate on the parameter side.

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 (Read) and resource (Mekler referral availability, terms and commission offer). It is distinguishable from mutating siblings like referral_accept_terms and referral_register, though it partially overlaps with referral_status and doesn't clarify the boundary.

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 explicit when-to-use guidance or alternatives are given. 'Current' implies a freshness-sensitive informational read, but the description never says when to prefer this over referral_status or referral_notices.

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=false; the description adds real context beyond that — the two-step challenge/sign handshake, oldest-first ordering, and the explicit 'No payment is authorized' note. It still does not explain what side effect makes the call non-read-only, leaving a small tension with readOnlyHint=false.

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?

Three tight sentences: purpose first, then arguments, then the auth flow, with zero filler. The parameter hints are packed inline rather than padded out.

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 paginated, auth-gated read with no output schema and 0% schema description coverage, it covers ordering, pagination args, and the auth sequence adequately. What a receipt contains and the purpose of new_proof remain unstated.

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 0% and all three params are undescribed nested objects, so the description carries the burden. It documents 'arguments' (optional cursor, limit 1-50) and the role of 'proof', but never explains 'new_proof' or the nested shapes — partial compensation only.

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 ('Page through a referrer's commission receipts') plus ordering ('oldest first'), which separates it from siblings like referral_status or referral_notices. It never explicitly names an alternative tool, so it sits just short of 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?

Gives a concrete calling protocol: call without proof to obtain a SIWx challenge, sign with the referrer wallet, then call again with proof, and notes payment is not required. It does not, however, say when to prefer this tool over the other referral_* siblings.

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=false; the description adds real behavioral context beyond that, disclosing the SIWx challenge/sign flow, the required proof round-trip, the exact terms acceptance requirement, and the reassuring 'No payment is authorized.' It doesn't describe failure modes or rate limits.

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?

Front-loaded with purpose, then arguments source, then the call flow, then a safety note. Dense but every sentence adds information; 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 3-object-param write tool with no output schema and no annotation detail, the description covers the auth flow and required inputs well. The unexplained new_proof parameter is the main remaining 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 coverage is 0%, so the description must carry the load. It usefully names the sub-fields of 'arguments' (terms_version, terms_digest) and explains 'proof' via the challenge/sign flow, but leaves 'new_proof' entirely unexplained.

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

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

States a specific verb+resource+outcome: 'Register a wallet as a Mekler referrer and receive a referral code.' It also ties the terms inputs to the sibling referral_program, giving some sibling differentiation, though it doesn't contrast with the other referral_* tools directly.

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

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

Gives an explicit two-step workflow: call without proof to obtain a SIWx challenge, sign with the referrer wallet, then call again with proof, and names referral_program as the source of terms_version/terms_digest. It lacks explicit when-not or alternative-tool routing, so not 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?

With only readOnlyHint=false in annotations, the description carries most of the burden and does well: it discloses the challenge/sign/retry auth flow, which wallet must sign, and the notable constraint 'No payment is authorized.' It omits reversibility, permission requirements, and failure 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?

Purpose is front-loaded in the first sentence, followed by the parameter mapping and the auth flow in order of need. Dense but every sentence carries information; the single long sentence for the flow is slightly run-on.

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 two-phase authenticated mutation with nested objects and no output schema, the description covers purpose, parameters, and the challenge-sign-retry sequence. It does not describe what the challenge or final response contains or what happens to the old wallet's state after rotation.

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 0% with three undocumented nested-object parameters, so the description must compensate — and it does, mapping arguments to old_wallet/new_wallet and identifying proof as the old wallet's proof and new_proof as the new wallet's. Types, formats, and the nesting structure inside arguments remain unspecified.

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 precise verb and resource — moving a referral registration to a new wallet while preserving history — which is clearly distinct from siblings like referral_register (new registration) and rotate_trial (trial rotation). An agent can pick this tool without opening the schema.

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

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

Gives an explicit two-step usage flow: call without proof to obtain a SIWx challenge, sign with the referrer wallet, then call again with proof. It does not, however, state when to prefer this over referral_register or other siblings, so it stops short of full alternative routing.

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 readOnlyHint=false, the description discloses the two-step challenge/proof handshake, the wallet-signing requirement, and a safety caveat ('No payment is authorized'). This explains why a conceptually 'read' tool can carry a non-read-only annotation, since issuing a challenge can persist state. It omits output shape and failure modes, but no output schema exists to cover those either.

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?

Three tight sentences, front-loaded with what is read, then the auth procedure, then the payment caveat. It is appropriately sized for the tool's complexity, with only the 'arguments: none' phrasing wasting or muddying space.

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?

Covers the read result and the authentication handshake, and enumerates returned fields in lieu of an output schema. It still leaves gaps for a tool with three nested-object params: the role of new_proof, the contents of the proof object, and any error/permission behavior are unaddressed.

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 0% across three nested-object parameters, so the schema carries no semantics at all. The description explains the 'proof' flow (call without, then with proof) but leaves 'new_proof' entirely unexplained, and its statement 'arguments: none' actively conflicts with the presence of an 'arguments' property 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?

States a specific verb ('Read') and resource (a registered referrer's code, referral link, accepted vs. current terms, action-required flag), so an agent knows exactly what it returns. It is naturally distinguishable from write-oriented siblings like referral_accept_terms and referral_register, though it never names them explicitly.

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

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

Gives concrete invocation instructions: no arguments needed, call without proof to receive a SIWx challenge, sign with the referrer wallet, then call again with proof. That is real procedural context and a clear when/how-to-call. It does not, however, contrast with alternatives such as referral_notices or referral_program.

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, yet the description adds real value beyond them: the 404 behavior for hidden/unknown IDs, the caveat that identity-reviewed branding claims remain unverified, and the explicit 'never signs payments' boundary. These are genuine behavioral constraints an agent could not derive from 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?

Front-loaded and compact, with the payload listed first. The trailing fragments 'No paid delivery certification.' and 'Never signs payments.' are telegraphic and lack framing, reading more as clipped boilerplate than earned content.

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 correctly enumerates what is returned and adds the 404 failure mode, which is what an agent needs. It omits any relation to sibling retrieval tools, which is the main remaining 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?

One parameter with 0% description coverage, and the description says nothing about listing_id — no format, no source, no hint that it is a 64-hex hash. The schema pattern carries the only meaning; the description does not compensate for the coverage gap.

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 (retrieve) and resource (one listing) and enumerates the payload: current grades, first seen, scan count, latest 100 grade observations. The singular framing implicitly separates it from bulk siblings like search_listings/search_services, but it never names an alternative, so it stops short of 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?

Gives one concrete usage condition — hidden or unknown listings return 404 — which tells the agent this only works on visible listings. However it offers no explicit when-to-use vs get_service, search_listings, or get_scan_report, leaving the routing decision to inference.

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=false and idempotentHint=false, so the safety profile is covered. The description adds the two-step challenge/proof workflow and notes that usage is preserved, but it omits auth requirements, failure modes, and what side effects occur beyond usage preservation.

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-loads 'Write:' before describing the two-step flow in a single sentence. 'Usage is preserved' is somewhat vague, but 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?

This is a complex six-parameter write with a oneOf schema, nested proof objects, no output schema, and minimal annotations. The description covers the two-step flow but omits the network enum, expected proof format, authentication needs, and return behavior, leaving significant gaps for correct invocation.

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?

With 0% schema description coverage, the description must compensate. It names and groups five of six parameters into two phases and explains that proofs are signed with both keys, but it never mentions the network parameter or the structure of the nested proof objects.

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

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

The description names a specific verb+resource: request a wallet-rotation challenge and submit signed proofs. It clearly distinguishes this write operation from the read-oriented sibling tools, though it does not explicitly reference them.

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 gives a clear two-step usage flow: first request a challenge with old_wallet/new_wallet/request_id, then submit old_proof/new_proof. It does not state when not to use the tool or name alternatives, but the procedural context is explicit.

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=true, openWorldHint=true), the description discloses real behavioral traits: fast mode returns an unsigned 402 (not a JSON response) and does not start a scan, idempotency_key drives compute-first admission and must be retained for retries, recovery needs the original input or proof, and it 'Never signs payments.' This is rich, specific disclosure that an agent cannot derive from the structured fields.

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 purpose is front-loaded and each subsequent sentence carries distinct operational information, so little is wasted. It is, however, extremely dense and reads as a packed sequence of clauses, which slightly hurts scannability.

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 6-parameter, no-output-schema, workflow-heavy tool, the description covers the quote/payment/recovery lifecycle and tells the agent to save and poll. Given there is no output schema, it could say more about the returned job/capability shape, and 'paths' remains unexplained, so it is complete but not exhaustive.

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?

With only 33% schema description coverage, the description pulls weight by explaining quote_mode's default, the idempotency_key/compute-first interaction, the timing of payment_signature, and the recovery_capability requirement. The 'paths' parameter is never addressed, leaving one gap, but the high-value parameters gain meaning 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 opening sentence gives a specific verb and resource: 'Start or recover an asynchronous x402 conformance scan.' It also separates itself from at least one sibling by name ('use get_scan_status for capability polling'). The jargon ('origin-only calls', 'compute-first admission') slightly muddies the core purpose, keeping it from a clean 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?

It states concrete when-to conditions: new origin-only calls default to quote_mode fast and return a quote without scanning; payment_signature should be resent only after independent payment authorization; recovery requires the original input or proof. It names get_scan_status as the polling alternative. It stops short of explicitly enumerating when NOT to call scan_origin versus all siblings, so it is not a full 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 already cover read-only/idempotent safety, and the description adds genuinely useful context beyond them: default 20 / max 100 page size, signed snapshot cursors valid 24 hours, and that hiding and suppression still apply to old cursors. 'Never signs payments' also preempts a plausible agent misread of an x402 listing search. It stops short of describing return shape or error 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?

Compact and front-loaded: facet list first, then paging/cursor rules, then trust caveats, then the safety disclaimer. Every clause carries information and none is redundant 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 and nine parameters at 0% schema coverage, the description does well on inputs but says nothing about what a listing result contains, how pagination terminates, or empty-result behavior. Adequate for invoking the tool, thin for interpreting its 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?

Schema description coverage is 0%, so the description carries the full burden, and it does reference all nine parameters (text, host, category, grade, owner_verified, featured, sort, limit, cursor) while adding semantics the schema lacks, such as cursor lifetime and sort options. It still omits matching syntax for `text`/`host` and the meaning of filtering on an absent value.

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

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

States a specific verb (search) and resource (scanned x402 services) and enumerates the filterable facets, so the purpose is unambiguous. However, it never distinguishes this tool from the near-identical sibling `search_services` (or `retrieve_listing`/`get_service`), so an agent cannot choose between them from the description alone.

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 through its filter list but gives no explicit when-to-use, when-not-to-use, or alternative routing, which is a real gap given that `search_services` and `export_listings` sit right beside it. The only constraint offered is the behavioral note that it never signs payments.

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 behavioral burden, and it discloses almost nothing: no indication of whether the query is keyword or natural-language, how many results return, whether auth or a referral code is required, or how 'exclusions and useful combinations' affect results. The one behavioral hint ('exclusions and useful combinations') is too vague to be actionable.

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?

It is a single short sentence with no waste, but its brevity stems from under-specification rather than tight writing, and the load-bearing phrase about exclusions/combinations is appended after the vague core instead of leading with concrete behavior.

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

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

For a 2-parameter search tool with no annotations, no output schema, and 0% param coverage, the description should explain query semantics, result scope, and the referral_code requirement; it does none of these, leaving the agent guessing on every invocation detail.

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 0% and two parameters exist, so the description must compensate and does not. 'for a task' weakly hints that 'query' is a task description, but 'referral_code' (22-64 chars) is never explained and no format, syntax, or matching semantics are given for either 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 implies a search/lookup tool ('Find ... for a task') but the key resource is named in opaque jargon ('Mekler paid operations') rather than as services, and the trailing phrase 'including exclusions and useful combinations' muddies rather than clarifies what is returned. It is not a tautology, but an agent cannot confidently distinguish this from get_service or the referral_* siblings.

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?

There is no when-to-use statement, no prerequisite, and no mention of the alternative get_service for single-service retrieval. Nothing tells the agent when this search is preferable to the get_* 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?

Adds substantial behavior beyond the annotations: a one-hour expiry on the challenge, a required publish step at an HTTPS well-known URL, a secrecy constraint on the requester key, a scan prerequisite, and two explicit scope boundaries (no payment/target credentials sent, never signs payments). This is exactly the kind of context annotations like readOnlyHint=false and idempotentHint=false cannot convey.

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?

Six short sentences, front-loaded with the core action, expiry, and the publish instruction. Slight redundancy: secrecy of the requester key is stated twice ('your private ... key' plus 'Keep the requester key private'), and the two payment/credentials sentences overlap.

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 compensates by telling the agent what to do with the return value (publish the returned JSON at its well-known URL) and what the prerequisites are. It does not describe the JSON's shape, which is a minor gap since the agent must publish it verbatim.

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 0%, so the description has to carry the load. It explains requester_key well ('private random 32-byte ... in lowercase hex' explains the ^[a-f0-9]{64}$ pattern), but 'origin' is only indirectly implied by 'domain challenge' and its URI format is never elaborated.

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

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

States a specific verb+resource: 'Start a one-hour domain challenge' bound to a requester key, which is clearly distinct from confirm_ownership_proof and scan_origin. It never names the sibling it hands off to, so differentiation is inferable rather than explicit.

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?

'A completed scan is required before confirmation' implies the ordering with confirm_ownership_proof and the existence of a follow-up step, but the alternative tool is never named and there is no when-not-to-use guidance. Usage is implied rather than spelled out.

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 annotations only covering readOnly=false and idempotent=true, the description carries real extra weight: domain-proof recheck after seven days, denial on failed/stale/revoked/expired credentials, 409 on concurrent writes, and the precise blast radius of suppression (current reads, new exports/feed pages, old search cursors) versus recoverable purchased snapshots. It even disclaims payment signing, which is meaningful scope information.

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?

Dense but front-loaded, leading with the control mechanism and operations before the failure and scope details. Every sentence adds information, though the trailing 'Never signs payments' is slightly tangential.

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 six-parameter mutation with no output schema, the description is behaviorally thorough: failure modes, concurrency, and suppression scope are all covered. The main gap is per-parameter meaning, but the operational context an agent needs to call it correctly is largely present.

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 0%, so the description must compensate. It hints at the credential header and the 'expected revision' (optimistic concurrency) but never explains listing_id, the individual hidden/suppress_branding/revoke booleans, or how revision mismatches are handled, leaving most of six parameters undocumented.

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 specific operations on a specific resource: hide a listing, suppress branding, revoke access, all via a named control header and revision. An agent can tell it is a mutation of listing visibility/access, though it does not explicitly contrast itself with siblings like retrieve_listing or export_listings.

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 gives procedural invocation context (use the X-Mekler-Listing-Control header and the expected revision) and failure conditions, but never states when to choose this tool over an alternative or the prerequisite to obtaining a valid credential. Usage is implied rather than directed.

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