Skip to main content
Glama

Preview work route

plan_work
Read-onlyIdempotent

Routing step 1 of 3: preview which providers could do a job. Given an objective, required capabilities and a max budget, return the eligible candidates with prices without saving anything. Use it to compare options before committing; to submit the work use route_work, and to read a route you already created use get_route. Creates no route, order, checkout or payment and moves no funds. Requires a registered-agent API key with agent:read as a Bearer token (register at POST /api/agents/register); limited to 10 calls per minute per agent. Returns {persisted: false, funds_moved: false, plan: {objective, required_capabilities, max_budget, candidates, ...}, planning: {examined, truncated, candidate_count}}. Free.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "client_reference": "<client_reference>",
      "objective": "<objective>",
      "required_capabilities": "<required_capabilities>",
      "max_budget": "<max_budget>"
    },
    "name": "plan_work"
  }
}

Input Schema

NameRequiredDescriptionDefault
inputNoOptional JSON input for the provider; it must satisfy the candidate service input_schema.
objectiveYesPlain-language statement of the work you want done, e.g. "Summarize the five most-cited 2026 papers on agent evaluation".
max_budgetYesHighest total price you accept, as a USD decimal string, e.g. {"amount":"5.00","currency":"USD"}. Services above it are excluded.
retry_policyNoOptional retry limit if a provider fails.
verificationNoOptional delivery checks a candidate must support. Omit for the default buyer_review.
payment_policyNoOptional payment rail restriction.
client_referenceYesYour own idempotency key for this request, e.g. "research-2026-11-15-a". Reuse it exactly when retrying the same request.
deadline_secondsNoOptional time limit for delivery, in seconds (up to 30 days).
provider_requirementsNoOptional buyer requirements, intersected with saved policy at planning, reservation and funding. Every requested capability must meet both backed thresholds when either is present. Buyer accounts are not verified independent people. Omitting this object allows claims; it grants no payment authority.
required_capabilitiesYesCanonical capability IDs or known aliases every candidate must offer; get them from get_capabilities or resolve_capabilities.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • addedInput schema / properties / client_reference / description
      Added value: +"Your own idempotency key for this request, e.g. \"research-2026-11-15-a\". Reuse it exactly when retrying the same request."
    • addedInput schema / properties / deadline_seconds / description
      Added value: +"Optional time limit for delivery, in seconds (up to 30 days)."
    • addedInput schema / properties / input / description
      Added value: +"Optional JSON input for the provider; it must satisfy the candidate service input_schema."
    • addedInput schema / properties / max_budget / description
      Added value: +"Highest total price you accept, as a USD decimal string, e.g. {\"amount\":\"5.00\",\"currency\":\"USD\"}. Services above it are excluded."
    • addedInput schema / properties / max_budget / properties / amount / description
      Added value: +"USD decimal string, e.g. \"5.00\""
    • addedInput schema / properties / objective / description
      Added value: +"Plain-language statement of the work you want done, e.g. \"Summarize the five most-cited 2026 papers on agent evaluation\"."
    • addedInput schema / properties / payment_policy / description
      Added value: +"Optional payment rail restriction."
    • addedInput schema / properties / required_capabilities / description
      Added value: +"Canonical capability IDs or known aliases every candidate must offer; get them from get_capabilities or resolve_capabilities."
    • addedInput schema / properties / retry_policy / description
      Added value: +"Optional retry limit if a provider fails."
    • addedInput schema / properties / retry_policy / properties / max_attempts / description
      Added value: +"Total provider attempts, 1 to 3."
    • addedInput schema / properties / verification / description
      Added value: +"Optional delivery checks a candidate must support. Omit for the default buyer_review."
  2. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds substantial non-schema context: it explicitly disclaims creating a route, order, checkout or payment, states no funds move, names the auth requirement (registered-agent key with agent:read as Bearer token, plus the registration endpoint), discloses a 10-calls-per-minute rate limit, and notes the call is free. These are real operational facts an agent cannot get 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.

Conciseness5/5

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

Front-loaded with the workflow position and purpose in the first clause, then constraints, then routing alternatives, then the return shape. Every sentence carries a distinct fact (scope, alternatives, side-effect disclaimer, auth/rate limit, response shape) with no repetition of the schema.

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?

For a 10-parameter tool with deeply nested objects and no output schema, the description supplies the missing pieces: the inline return shape ({persisted, funds_moved, plan, planning}) substitutes for an absent output schema, and auth, rate limit, cost and no-side-effect guarantees cover the operational gaps. Nothing an agent needs 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.

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description only restates the three headline inputs (objective, required capabilities, max budget) and adds no format or syntax detail beyond what the schema already documents; it says nothing about client_reference idempotency, verification, payment_policy or provider_requirements, which is acceptable only because the schema carries them.

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 and resource ('preview which providers could do a job'), names its position in a workflow ('Routing step 1 of 3'), and enumerates the inputs that drive the result. It explicitly separates itself from route_work (submit) and get_route (read an existing route), so an agent can pick it 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.

Usage Guidelines5/5

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

Gives an explicit when-to-use ('compare options before committing') plus named alternatives with the condition that selects each: route_work to submit the work, get_route to read a route you already created. There is no ambiguity about ordering in the 3-step routing flow.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources