PaidHandshake Exchange

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

With no annotations, the description carries the full burden, and it does disclose a key trait: 'only creates the checkout handoff and never silently charges the buyer,' which rules out a charge-on-create reading. However it omits other behavioral facts an agent would need, such as whether the URL is returned, URL expiry/reuse, idempotency of repeated calls, and any permission prerequisites.

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 sentences, no waste, and the purpose is front-loaded ahead of the routing guidance. Every clause either states intent or routes the agent to an alternative.

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-parameter handoff tool with no output schema, the description covers purpose, the safety-relevant no-silent-charge guarantee, and sibling routing, which is close to sufficient. It would be fully complete with a note on what is returned (the URL) and any auth or expiry constraints.

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 enum values (single/top3/full) and the search_id/result_id sources are already fully documented in the schema. The description adds no parameter-level detail beyond that, so the 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?

Specific verb and resource: 'Create a Stripe Checkout URL' after a PaidHandshake search for a buyer authorizing access to locked results. It also distinguishes itself from siblings by naming get_unlock_quote and by excluding recurring watches and machine-wallet jobs.

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 when-to-use (buyer wants to authorize access to locked results), when-not-to-use (recurring watches, machine-wallet jobs), and the alternative for the adjacent intent (get_unlock_quote if the buyer only needs pricing). Nothing is left 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?

With no annotations, the description carries the full burden and does well: it discloses the authentication requirement, that each run is a normal paid job bounded by max_price_cents plus delegated spending limits, and the 60-10080 minute cadence bound, with the 'rejected rather than overspending' behavior made explicit. It stops short of stating what happens to the watch on failure or partial-run outcomes, so it is strong but not exhaustive.

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 sentences, front-loaded with the purpose, then cost/cadence constraints, then the sibling routing rule. Nearly every clause earns its place; the 'Authenticated:' prefix is a slightly abrupt lead-in but still useful.

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 seven-parameter mutation with a nested constraints object and no output schema, the description covers purpose, prerequisites (auth), cost bounding, cadence limits and sibling routing. The remaining gap is the absence of any hint about the created watch's identifier/return, which is minor given no output schema is declared.

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 all seven parameters are already documented in the schema, establishing a baseline of 3. The description reinforces cost semantics (per-run cap plus delegated spending limits) but adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb+resource ('create a new recurring paid watch') and the use case (repeated research or monitoring). It explicitly differentiates itself from set_recurring_paid_watch and submit_paid_machine_job, so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use ('only to create a new watch') and names both alternatives with their own conditions: set_recurring_paid_watch for enable/disable of an existing watch, submit_paid_machine_job for one-time work. Nothing is left 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it returns exactly one paid-eligible verified record when available, and quality-held candidates are never substituted — a meaningful data-quality guarantee an agent cannot infer from annotations or schema.

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-loading the core purpose before the routing guidance and the data-quality caveat. No filler or restatement of the tool name.

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

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

There is no output schema, so the description must carry return-value meaning — it states what is returned (one paid-eligible verified record, quality-held candidates excluded). It does not describe the record's fields, but for a one-parameter sample tool this is close to complete.

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

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

Schema description coverage is 100%, and the single 'feed' parameter carries an enum of seven self-explanatory slugs, so the schema does the heavy lifting. The description only frames the parameter conceptually ('one canonical PaidHandshake inventory feed') without adding format or selection guidance beyond the enum.

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-only preview of one canonical PaidHandshake inventory feed') and constrains scope to a single feed. It explicitly names the sibling it is NOT (get_published_intelligence_sample), so an agent can disambiguate without opening either 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 prerequisite ('Use get_live_inventory first to discover feed inventory') and an explicit exclusion routed to an alternative ('use get_published_intelligence_sample instead for worker-published intelligence products'). Both when-to-use and when-not-to-use are covered.

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 safety profile itself: it declares the tool free and read-only and spells out the returned signals (worker heartbeat/status, feed state, completed paid-job counts). The caveat that background inventory generation is not counted as customer revenue preempts a plausible misreading of the counts. It stops short of operational detail such as auth requirements, rate limits, or data freshness.

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

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

Two sentences, front-loaded with the identity of the tool and the proof it provides, then the routing guidance. Dense but each clause carries information; the return-field enumeration and the revenue caveat both earn their 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?

With no output schema and no annotations, the description does the heavy lifting by enumerating what is returned and qualifying what the counts mean. That is enough for an agent to call and interpret it, though freshness or invocation cost details are absent.

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 and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline for a parameterless tool applies; no misleading param language is present.

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 (get fulfillment proof = operational evidence PaidHandshake has active fulfillment capacity) and enumerates the four signal classes returned. It also positions itself against siblings by ruling out inventory browsing (get_live_inventory) and single-job polling (get_paid_machine_job), so an agent can route correctly without opening another 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?

Contains an explicit when-to-use ('platform/fulfillment verification') plus two when-not cases that map cleanly onto named sibling concepts: purchasable inventory and polling one specific paid job. Nothing is left to inference about the appropriate call site.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing cost ('Free'), the snapshot nature (point-in-time view of canonical feeds), and the scope of included metrics.

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 sentences, both dense and front-loaded: the first defines the resource and payload, the second routes the agent among siblings. 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?

An output schema exists so return values need no prose, and annotations cover the safety profile. With zero parameters, the description supplies everything an agent needs to choose and invoke this tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline for a parameterless tool is 4.

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

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

States a specific verb+resource (read-only snapshot of canonical PaidHandshake inventory feeds) and enumerates the payload (paid-eligible counts, quality holds, freshness, prices, sample URLs). This clearly distinguishes it from the sibling catalog and sample tools.

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

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

Explicitly positions itself as 'the starting point for known feed inventory' and names three alternatives with the condition each suits: get_free_data_sample for one feed sample, get_published_intelligence_catalog for worker-published products, search_matches for ad hoc web discovery. Nothing is left 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?

With no annotations provided, the description carries the full burden and does part of that work well: it declares the call is 'Free, read-only,' which tells the agent no auth or mutation risk is involved. It does not state pagination, rate limits, or response format details, but the read-only/free framing plus the enumerated contents cover the most decision-relevant traits.

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

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

The description is two sentences, dense but front-loaded with the core purpose and terminating with the alternative-tool routing. Every clause adds information (free, read-only, the returned endpoint families, the sibling alternative), though the enumerated endpoint list is somewhat crowded.

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

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

There is no output schema, so the description must convey return content, and it does so by naming the endpoint families the guide covers. The closing 'related machine endpoints' is a slightly vague catch-all, and the response shape (a guide document vs. structured JSON) isn't specified, leaving a small gap for a discovery tool.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description adds no parameter-level detail because none is needed or possible here.

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

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

The description states a specific verb and resource ('onboarding guide' / 'machine enrollment route') and enumerates the payload it returns (Stripe wallet-funding, paid-job submission/polling, recurring-watch endpoints). It explicitly distinguishes itself from the sibling get_machine_wallet, so an agent can route without opening either 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 an explicit when-to-use condition ('when an agent needs to become a PaidHandshake machine buyer or discover the required API flow') and an explicit alternative with its precondition ('use get_machine_wallet after authentication to inspect an existing machine account'). The selection logic between the two tools is fully 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?

Annotations already supply readOnlyHint, idempotentHint, destructiveHint=false and closed-world hints, so the safety profile is covered. The description adds value beyond that: it is 'Free', and it discloses the availability states ('available or activation-ready', 'where active'), which tells the agent results may be conditional. It stops short of describing result shape or sorting, keeping it at a 4.

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 sentences, zero waste. The what is front-loaded, and the usage/alternative guidance follows immediately without 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?

With no output schema and no parameters, the description carries the burden of telling the agent what it gets back, and it does so at a conceptual level (list of payment rails with states). It does not specify result structure or ordering, but annotations and sibling context make this sufficient 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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool is 4. The text correctly implies no input is required.

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

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

States a specific verb and resource ('read-only discovery of machine payment rails') and scopes it precisely to PaidHandshake, naming concrete rail types (Stripe-funded delegated wallets, x402 Base-USDC). It distinguishes itself from get_machine_wallet by contrasting discovery of options with inspection of one wallet.

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 it ('an autonomous buyer needs to choose how to pay') and names the alternative with its own selection condition (get_machine_wallet for inspecting an authenticated machine's balance and limits). Nothing is left 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 carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description nonetheless adds real context beyond them: an authentication requirement, that it exposes balance and delegated spending limits, and that no funds move. It stops short of return format or freshness details, keeping it below 5.

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, all front-loaded: identity/scope first, then when-to-use and the alternative in a single closing sentence. Every clause carries 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?

With no output schema, the description compensates by naming what is returned (wallet balance and delegated spending limits) and confirming the read-only, no-funds-moved property. For a zero-parameter read tool this is complete.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Schema coverage is 100% (empty object), so this dimension is inherently non-blocking.

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-only wallet status for the current machine buyer') and immediately bounds the scope ('without moving funds'). An agent can distinguish it from nearby money tools 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 trigger ('Use this before submit_paid_machine_job to verify available budget') and names a sibling with the disambiguating condition ('get_machine_payment_options to discover funding and payment rails rather than account-specific balances'). Nothing is left 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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description usefully adds that the call is 'Free' (no cost/auth barrier), which is context beyond the annotations. It does not discuss rate limits or output shape, so it stops short of 5.

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 sentences, zero waste: the first front-loads what the tool is and returns, the second handles routing. Nothing is redundant with the name or annotations.

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 no-param, no-output-schema discovery tool with full annotation coverage, the description gives an adequate summary of the return categories and how to proceed afterwards. It is essentially complete; only a slightly richer sense of the return structure would push it higher.

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 parameters, so there is no argument semantics to explain and the baseline for a no-param tool is 4. The description correctly implies the tool is a zero-input discovery call.

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 ('capability map for PaidHandshake Exchange') and enumerates exactly what it returns: feed families, machine endpoints, payment rails, and operating rules. It is clearly distinguishable from siblings like get_machine_wallet or get_machine_onboarding without opening any 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?

Explicitly says 'Use this first' and names two alternatives with the conditions that select them: get_machine_onboarding for enrollment/setup and get_machine_wallet for authenticated balance/limits. This is a textbook when-to-use / alternative routing statement.

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

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

With no annotations, the description carries the full burden and does well: it discloses the authentication requirement, the read-only nature, and the lifecycle states (queued, working, completed, failed) plus availability of a result. It stops short of describing polling cadence, rate limits, or how long results persist, which leaves a small gap for a polling endpoint.

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 sentences, front-loaded with the core purpose, then routing guidance. Every clause earns its place and nothing is repeated from the schema.

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 and no annotations, so the description must cover the return shape; it names the four possible states and mentions an optional result, which is enough to set expectations for a status poll. Minor gaps remain around result payload shape and polling behavior, but nothing an agent needs to invoke the tool 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 100%, so job_id's origin, format, and ownership scoping are already documented in the schema. The description restates that the id comes from submit_paid_machine_job without adding syntax or edge-case detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Authenticated, read-only polling for a previously submitted paid machine job') and enumerates the states it returns. It explicitly distinguishes itself from submit_paid_machine_job and quote_paid_machine_job, so an agent can route correctly without opening any 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 the exact precondition (use the job_id returned by submit_paid_machine_job) and names the alternative for a different need ('use quote_paid_machine_job before submission, not this tool, when you only need a price estimate'). Both when-to-use and when-not-to-use are 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?

Annotations already declare readOnly, idempotent, non-destructive, non-openWorld, so the safety profile is covered; the description adds 'free' (no payment/quote step required) and enumerates the returned content types. It does not mention rate limits, auth, or result sizing, but for a zero-param read tool that is a minor omission.

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 sentences, no filler, with the scope statement first and the routing/alternative guidance second. Every clause earns its place.

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 enumerating the returned fields, and it covers use case plus sibling routing. An agent has everything needed to call it correctly and interpret the result at a high level.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description usefully notes the payload categories even though no parameters exist.

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: a free, read-only catalog of structured intelligence products, with the payload spelled out (paid-eligible counts, prices, sample paths, x402 purchase routes). It explicitly distinguishes itself from both get_published_intelligence_sample and get_live_inventory.

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 both the when ('discover product names before calling get_published_intelligence_sample') and the when-not ('use get_live_inventory instead for canonical PaidHandshake feed inventory'). The alternative and the selecting condition are stated outright.

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

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

With no annotations, the description carries the full burden and does well: it declares the operation is 'Free' and 'read-only' and that it returns 'one paid-eligible structured record' for inspection before purchase. It doesn't mention rate limits or any auth requirement, but for a free read-only sample the key behavioral facts are covered.

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 essential nature of the tool ('Free, read-only sample...') followed by return semantics and sibling routing in a single dense sentence. Every clause earns its place, though the semicolon-chained alternatives make it 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?

No output schema exists, so the description compensates by explaining the return ('one paid-eligible structured record' for inspecting quality and fields). Combined with the fully-covered single param and explicit sibling routing, an agent has enough to invoke correctly, though return fields aren't enumerated.

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 single 'product' param and its enum are already fully documented in the schema. The description adds only framing ('one worker-published intelligence product') beyond the schema, which is the baseline expectation rather than extra 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 and resource ('read-only sample of one worker-published intelligence product') and clarifies scope ('one paid-eligible structured record'). It explicitly distinguishes itself from two siblings, get_published_intelligence_catalog (discovery) and get_free_data_sample (inventory-feed path), so an agent can select it without opening other schemas.

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

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

Gives the exact precondition and alternative routing: use get_published_intelligence_catalog first to discover product names, and get_free_data_sample for the separate inventory-feed sample path. The use case (inspect quality/fields before purchasing) is stated, so when-to-use and when-to-use-something-else are both 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?

Annotations already cover readOnly/idempotent/non-destructive, and the description adds the meaningful business context that the lookup is free and neither creates checkout nor charges the buyer. It does not describe return shape or any rate/refresh behavior, so it stops short of full transparency.

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 the free/read-only nature of the call, followed by outcome ('returns packages and prices') and then routing guidance. No redundant or throwaway 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?

For a one-parameter, no-output-schema tool, the description covers purpose, side-effect profile, and workflow placement. The only gap is the precise return structure (package fields, price format), which an agent must infer from the prose.

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 the single search_id parameter is fully documented in the schema itself. The description only restates that the exact search_id from search_matches should be passed, adding no syntax or format detail beyond the schema, so the 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?

Specific verb and resource: a free, read-only pricing lookup for unlock packages tied to an existing search_matches search_id. It distinguishes itself from the checkout sibling by explicitly stating it does not create checkout or charge the buyer.

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 routing: use create_checkout only after a buyer picks a package, and use search_matches first if no search_id exists. Both the successor and the prerequisite are named with their selecting conditions.

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 the read-only/idempotent/non-destructive safety profile, so the bar is lower, yet the description still adds that access is authenticated and describes what is returned (saved watches with identifiers, configuration, enabled status). This is useful extra context, though it says nothing about pagination or limits for a listing operation.

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: capability and scope first, return content second, sibling routing last. Every sentence carries distinct 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?

With no output schema present, the description compensates by summarizing the return payload (identifiers, configuration, enabled status), and with zero parameters and covered annotations nothing an agent needs to call it 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing in the schema requiring explanation. No parameter semantics are needed here.

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

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

States a specific verb and resource ('listing of recurring paid watches') plus scope ('belonging to the current machine buyer'), which immediately separates it from the sibling write tools. An agent can identify the operation 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?

Explicitly routes the agent: use it to obtain a watch_id before set_recurring_paid_watch, and use create_recurring_paid_watch to make a new watch. The when-to-use condition and both alternatives are named directly.

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 must carry the safety profile, and it does: 'free,' 'read-only,' and no money reserved until acceptance. It also discloses a fallback behavior ('unknown task labels may be mapped to a compatible live-worker capability'). Auth requirements, rate limits, and return shape are not covered, keeping it short of a 5.

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 tightly packed sentences, front-loaded with the defining property (free, read-only estimate) and then sequencing and edge-case behavior. 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 quote/estimate tool with no output schema and no annotations, the description covers purpose, routing to the execution sibling, cost/safety profile, and label-mapping fallback. It stops short of describing the quote payload, but that is 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%, so the schema already documents task_type and the constraints object in detail. The description restates the same task-label categories (research, sourcing, verification) without adding syntax, format, or constraint-handling detail beyond the schema. 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?

States a specific verb and resource — a 'free, read-only price estimate for delegated machine work' — and immediately scopes it as happening 'before any job is submitted or money is reserved.' This clearly separates it from the execution sibling submit_paid_machine_job and the retrieval sibling get_paid_machine_job.

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 names the alternative and the sequencing condition: 'after accepting the quote, use submit_paid_machine_job for execution.' It also enumerates qualifying work types (custom public-web research, sourcing, verification, commercial intelligence), leaving nothing 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?

No annotations exist, so the description carries full burden; it declares the tool read-only and discloses what comes back (one evidence-bearing proof result, locked ranked previews, pricing, a reusable search_id). It does not cover auth requirements, rate limits, or pagination, which keeps it short of a 5.

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 sentences, purpose front-loaded, then outputs, then alternatives; no wasted text. The first sentence is dense but still readable. Slightly heavy but earns its 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 steps in to describe the return payload (proof result, previews, pricing, search_id), and with no annotations it supplies the read-only nature. Only auth and pagination behavior remain unaddressed, which is a minor gap for a discovery tool.

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

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

Schema description coverage is 100% and the single 'query' parameter is fully documented with length bounds, constraint types, and intent. The description adds no meaning beyond the schema for the parameter itself, 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?

States a specific verb (search/discovery) and resource (current public or authorized web information), with the scope spelled out. It distinguishes itself from get_live_inventory, get_free_data_sample, and quote_paid_machine_job by name, so an agent can route correctly without opening schemas.

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

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

Explicitly gives the selection condition (use when the request is not already covered by a known PaidHandshake inventory product) and names the alternatives for known-inventory and custom-research cases. Both the when and the when-not paths are present.

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 burden and does disclose key traits: the call requires authentication, it mutates only the enabled state of an existing watch, and disabling affects only future runs. It stops short of stating whether an in-flight run is cancelled, whether the change is reversible, or what the call returns.

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 compact sentences, front-loaded with the core state-change purpose and the enable/disable semantics, followed by the routing to sibling tools. No filler, and the negative scope ('does not create... or edit its query') earns its place.

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-parameter mutation with no output schema and no annotations, the description covers auth, mutation scope, and sibling routing adequately. It omits only the return shape/idempotency details, which are minor for a simple boolean toggle.

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 both parameters are already documented; the description largely restates the enabled semantics (future scheduled executions on/off) and adds the note that cadence and spending limits are preserved. This adds marginal meaning beyond the schema, consistent with the baseline 3 for full coverage.

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

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

States a specific verb and resource ('Authenticated state change for an existing recurring paid watch') and explicitly scopes what it is not: it does not create a watch or edit its query. This lets an agent separate it from create_recurring_paid_watch and the read-only list tool without opening any 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 explicit when-to-use branches (enabled=true for future scheduled runs under saved cadence/limits, enabled=false to stop future runs) and names the alternatives for the adjacent operations: create_recurring_paid_watch to create one and list_recurring_paid_watches to obtain an existing watch_id. Nothing is left 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 establish the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real context beyond them: spending is bounded by the machine's delegated wallet and platform limits, work is routed to a compatible worker capability, and the call returns a job_id for polling. The idempotency_key in the schema is consistent with idempotentHint=false (opt-in, not inherent), so no contradiction.

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 sentences, each load-bearing: the first defines the operation and its precondition, the second the spending/routing/return behavior, the third the alternatives. The core action is front-loaded in the opening clause 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?

Despite a five-parameter schema with a nested object and no output schema, the description covers everything an agent needs: auth requirement, spend authorization, routing behavior, return value (job_id) and how to consume it, plus alternative tools for adjacent cases. Nothing material 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 100%, so all five parameters are already fully documented, and the description names no parameter-specific formats or constraints beyond what the schema states. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb+resource ('submits a one-time machine job') along with the precondition ('after the buyer has accepted the task and spending cap'), and explicitly distinguishes itself from the recurring sibling. An agent can tell it apart from create_recurring_paid_watch and quote_paid_machine_job 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?

Gives explicit when-to-use routing: 'Use quote_paid_machine_job first when the price is not yet known; use create_recurring_paid_watch instead for repeated work.' It also names the authentication prerequisite and the buyer-acceptance precondition, leaving nothing to inference about when this tool is the right choice.

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