PaidHandshake Exchange

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 disclose the single most important trait: no silent charging, the URL is returned for explicit user authorization. It still omits whether a pending record is created, URL expiry, idempotency, and permission requirements.

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

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

Two sentences, no filler, with the operation front-loaded in the first clause and the safety contract immediately after. Every sentence 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 mutation-adjacent tool with no annotations, no output schema, and three parameters, the description covers purpose and the authorization contract but leaves the agent guessing about the surrounding workflow, parameter meanings, and what the returned URL can be used for or how long it lives.

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 only 33% and the description adds no parameter meaning at all: it never explains the single/top3/full package enum, what search_id identifies, or how result_id pairs with package=single. With low coverage, the description was expected to compensate and does not.

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: create a Stripe Checkout URL for a PaidHandshake result package. That is far more specific than a generic 'create' tool, but it never names or distinguishes itself from the adjacent money-flow siblings (get_unlock_quote, quote_paid_machine_job, submit_paid_machine_job), so an agent must infer its place in the sequence.

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 workflow step ('return the URL to the user for explicit authorization') and the schema hints at the prerequisite (result_id from a locked preview), but it never states explicitly when to call this versus get_unlock_quote or quote_paid_machine_job, nor any preconditions. 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.

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

No annotations are provided, so the description carries the full behavioral burden. 'Return' implies a read-only retrieval, but the description does not disclose authentication requirements, rate limits, side effects, or response format, leaving most behavioral traits unspecified.

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 a single front-loaded sentence with no filler. The list format is dense but appropriate for enumerating the endpoint categories returned.

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

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

For a zero-parameter read tool, the description is adequate enough to invoke correctly, but with no output schema it does not explain the returned data structure, and it leaves usage context thin. It covers the purpose but not the full context an agent might need.

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 are no parameter semantics for the description to clarify. Per the rubric, a zero-parameter tool receives a baseline of 4.

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

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

The description names a specific verb ('Return') and resource ('self-service REST enrollment, Stripe wallet funding, paid-job and polling endpoints'), making the tool's purpose clear. It does not explicitly differentiate itself from siblings like get_machine_wallet or get_paidhandshake_capabilities, but the onboarding focus is distinct enough to be actionable.

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 identifies the target audience ('autonomous agent buyers') but gives no when-to-use guidance, prerequisites, or comparisons to sibling tools. An agent must infer that this is the entry point for machine onboarding rather than being told 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?

No annotations are provided, so the description carries the full burden. It does disclose useful behavioral context by specifying the result is scoped to the 'authenticated machine', implying per-caller isolation, but says nothing about auth requirements, rate limits, or read-only semantics beyond the verb 'Return'.

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?

One compact sentence with the verb and both returned resources front-loaded and zero filler. Nothing could be trimmed without losing meaning.

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

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

For a zero-parameter read tool with no annotations and no output schema, the description covers the essentials by naming both returned values. It stops short of describing the response shape or units, but that is a minor gap given the tool's simplicity.

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 4 applies. The schema is trivially empty and nothing in the description conflicts with it.

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 (Return) and two concrete resources (wallet balance, delegated spending limits) scoped to the authenticated machine. This clearly separates it from siblings like create_checkout or get_unlock_quote, though it never explicitly names an alternative tool.

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?

Usage is implied by the returned content — an agent infers it should call this to inspect machine wallet state. However, there is no explicit when-to-use, when-not, or reference to any sibling such as get_paidhandshake_capabilities, which could plausibly overlap.

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 are provided, so the description carries the full burden. It discloses the content domains covered (endpoints, payment behavior, operating principles), which is meaningful for a zero-param tool, but says nothing about return format, whether it is read-only/safe, or how large the response is.

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. It is appropriately sized, though it could have used one more clause to steer usage without bloat.

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 is the only source of information about the return payload, and it does not describe shape or scope of the returned capability data. Adequate as a minimum-viable description, but incomplete for a tool with zero structured support.

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. Baseline 4 applies for a no-parameter 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 (Describe) and a clear resource (PaidHandshake Exchange machine endpoints, payment behavior, operating principles). It is distinguishable from the transactional siblings like create_checkout or get_machine_wallet, though it doesn't explicitly name itself as the discovery/introspection entry point.

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 explicit guidance on when to call this versus the other machine tools (onboarding, wallet, quotes, jobs). Usage is only implied by the 'describe' framing; an agent gets no condition or ordering advice.

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. It usefully discloses that the same phm_ bearer token from submission is required, but says nothing about what a poll returns, job state transitions, whether polling is idempotent or rate-limited, or what happens if the job is unknown or still running — the core semantics of a polling tool.

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?

One tight sentence with the operation front-loaded and no filler. It is efficient, though it is arguably too compressed for the amount of behavior a polling endpoint needs to convey.

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 annotations, no output schema, and an undocumented parameter mean the description is the only channel for agent-relevant context, and it omits return shape, job-state interpretation, and retry behavior. For a polling tool this leaves an agent unable to interpret results confidently.

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 single job_id parameter has 0% schema description coverage and is not explained in the description either. The phrase 'previously submitted' hints that the id originates from submit_paid_machine_job, but the description adds no format, source, or validity detail beyond that implication.

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 (poll) and resource (a previously submitted autonomous machine job), which cleanly separates it from submit_paid_machine_job and quote_paid_machine_job in the sibling list. It stops short of naming those siblings explicitly, but the 'previously submitted' qualifier makes the lifecycle position unambiguous.

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?

'Poll a previously submitted' implies usage after submission, and the bearer-token clause is a real prerequisite. There is no explicit statement of when not to use it, no polling cadence or termination guidance, and no pointer to the submit/quote siblings as the counterpart operations.

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 are provided, so the description carries the full disclosure burden. 'Get' weakly implies a read, but nothing states whether the call is non-destructive, whether it requires auth, whether quoted prices expire or are guaranteed, or what happens if the results were already unlocked — all meaningful for a quote 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?

One sentence, front-loaded with the core action and ending with the scoping constraint. No filler or redundant 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 and no annotations, so the description is the only source of contract detail; it covers purpose and the input's origin but not the shape of the quote returned or edge cases (expired search, already-unlocked results). Adequate for a simple one-parameter read, but with clear gaps.

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 a single parameter at 0% schema description coverage, the description must compensate. It does clarify that search_id refers to an existing PaidHandshake search, but gives no format, no source (where the id comes from), and no failure behavior for an invalid id, so compensation is partial.

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 prices for unlocking additional ranked results) plus the scope constraint (an existing PaidHandshake search). An agent can tell this is a pricing lookup rather than the purchase itself, but no sibling is named or contrasted.

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?

Phrase 'from an existing PaidHandshake search' implies the prerequisite that a search must already exist and supplies its id, which is useful routing context. However, it never says when to call this versus create_checkout (the natural follow-on purchase step) or any other sibling, so usage is only implied.

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. It usefully discloses the cost profile (no-cost) and the non-committal nature of a quote, but says nothing about auth requirements, rate limits, what the quote contains, or what task_type accepts. Partial behavioral coverage only.

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, purpose front-loaded in the first. The second sentence's long category list is somewhat padded with 'and other lawful current-data tasks,' but it is far from bloated.

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, no annotations, and a nested parameter at 0% schema coverage. The description omits quote structure, constraints shape, valid task_type values, and follow-up steps, so an agent lacks enough to invoke this confidently beyond the required field.

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% with 2 parameters, one a nested 'constraints' object. The description lists task categories (research, procurement, bids, vendors...) that loosely hint at task_type values but never maps them to the parameter, and leaves the nested constraints object 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 and resource: 'get a no-cost quote for deeper PaidHandshake worker fulfillment.' The cost-free and pre-spend framing distinguishes it functionally from get_unlock_quote and submit_paid_machine_job, 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?

'before a machine account spends anything' implies the timing context (pre-commitment estimation), which is genuinely useful. However, it names no alternatives and gives no explicit when-not guidance versus get_unlock_quote or submit_paid_machine_job, leaving routing 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 it partially does so by noting that results include a cited proof source, ranked previews, pricing, and a reusable search_id, and that the information is public or authorized. It still omits key behavioral details such as read-only nature, rate limits, authentication requirements, or pagination 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?

The definition is front-loaded with the core action and resource, followed by a clear return-value sentence. The extensive enumeration of search domains is dense but arguably necessary for scope, though it could be slightly trimmed without losing meaning.

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

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

Given one fully documented parameter and no annotations or output schema, the description provides adequate scope and return-value information for an agent to invoke it. It stops short of explaining pagination or result limits, but those gaps are minor for a search 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 schema fully documents the single query parameter, including guidance to include meaningful constraints, so the baseline is 3. The description adds no additional meaning or syntax beyond what the schema already provides.

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

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

The description states a specific verb (Search) and resource (PaidHandshake) and enumerates the broad information domains it covers. It is clearly distinguishable from the sibling tools, which deal with checkout, onboarding, wallet, jobs, and quotes rather than general search.

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

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

The description implies the tool is for retrieving current public or authorized information across many categories, giving an implied use case. However, it does not explicitly state when to use this tool versus alternatives or provide any exclusions or prerequisites.

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 auth, auto-authorization limits (delegated wallet, per-call/daily/monthly/platform), and that workers return structured source evidence. It omits critical mutation behavior such as charging, job lifecycle, idempotency, cancellation, and how/when to poll for results.

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

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

Two compact sentences front-load the submit action and auth condition. The authorization-limit clause is dense but earns its place; no obvious 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 complex paid, asynchronous job-submission tool with no annotations, no output schema, and 0% schema descriptions, this is insufficient. It gives high-level auth/return context but omits parameter semantics, result retrieval, and key side-effect details.

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% for five parameters, so the description must compensate. It names max_price_cents only in passing and gives no meaning for query, task_type, constraints, or idempotency_key, leaving required and optional parameters essentially 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?

Specific verb 'submit' and resource 'paid research' (machine job), with auth and payment scope. Distinguishes somewhat from read/quote siblings by 'submit deeper paid research', but does not name an alternative.

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?

States the caller condition (authenticated phm_ agents) and intent scope (supported lawful intent), implying when to use. It does not mention the quote_paid_machine_job or get_paid_machine_job alternatives, so routing guidance is incomplete.

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