Skip to main content
Glama

PaidHandshake Exchange

by com.paidhandshake
OverviewDiscussionsAdmin

submit_paid_machine_job

Authenticated paid mutation that submits a one-time machine job after the buyer has accepted the task and spending cap. PaidHandshake authorizes work only inside the machine's delegated wallet and platform spending limits, routes it to a compatible worker capability, and returns a job_id for later polling with get_paid_machine_job. Use quote_paid_machine_job first when the price is not yet known; use create_recurring_paid_watch instead for repeated work.

Input Schema

NameRequiredDescriptionDefault
queryYesNatural-language task to execute. Include the desired outcome and important location, timing, scope, evidence, filtering or result requirements.
task_typeNoOptional routing label describing the work category or intent. Use a descriptive capability label when known; otherwise PaidHandshake can route compatible work from the request.
constraintsNoOptional structured task requirements such as location, date range, maximum results, verification requirements, exclusions, budget or other execution limits.
idempotency_keyNoOptional caller-generated stable key for the same intended paid submission. Reuse the same key when retrying an uncertain request so an accidental duplicate job can be avoided.
max_price_centsYesMaximum amount in USD cents this machine authorizes for this single job. The request remains subject to delegated wallet, per-call, daily, monthly and platform spending limits.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / constraints / description
      Added value: +"Optional structured task requirements such as location, date range, maximum results, verification requirements, exclusions, budget or other execution limits."
    • addedInput schema / properties / idempotency_key / description
      Added value: +"Optional caller-generated stable key for the same intended paid submission. Reuse the same key when retrying an uncertain request so an accidental duplicate job can be avoided."
    • addedInput schema / properties / max_price_cents / description
      Added value: +"Maximum amount in USD cents this machine authorizes for this single job. The request remains subject to delegated wallet, per-call, daily, monthly and platform spending limits."
    • addedInput schema / properties / query / description
      Added value: +"Natural-language task to execute. Include the desired outcome and important location, timing, scope, evidence, filtering or result requirements."
    • addedInput schema / properties / task_type / description
      Added value: +"Optional routing label describing the work category or intent. Use a descriptive capability label when known; otherwise PaidHandshake can route compatible work from the request."
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

All PaidHandshake Exchange toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources