Skip to main content
Glama

Submit purchase intent

submit_purchase_intent
Idempotent

Declare a planned purchase before buying so policy can auto-approve, pause for human review, or deny; repeat submissions return the original intent.

Instructions

Declare a purchase before making it. Policy decides: auto-approve, pause for a human (Slack/Discord), or deny. Submitting the same agent_id + task_id + vendor + amount again inside the idempotency window returns the original intent instead of creating a second one.

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": {
      "agent_id": "<agent_id>",
      "task_id": "<task_id>",
      "task_goal": "<task_goal>",
      "vendor_domain": "<vendor_domain>",
      "amount": "<amount>",
      "is_recurring": "<is_recurring>"
    },
    "name": "submit_purchase_intent"
  }
}

Input Schema

NameRequiredDescriptionDefault
amountYesAmount to spend, in major units of the currency (e.g. 15.00).
task_idYesIdentifier of the task this purchase serves, e.g. '102'.
agent_idYesStable identifier of the calling agent, e.g. 'invoice-bot'.
currencyNoISO 4217 currency code.USD
reasoningNoOptional step-by-step reasoning that led to this purchase. Stored in the audit log.
task_goalYesWhat the agent is trying to accomplish and why this purchase is needed.
is_recurringYesTrue if this creates a subscription, trial that auto-renews, or any repeat charge.
vendor_domainYesMerchant domain, e.g. 'pdfocr.io'.
alternatives_attemptedNoFree or already-owned options the agent tried first, and why they failed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations only supply idempotentHint=true, yet the description adds real behavior: the three policy outcomes including human interruption via Slack/Discord, and the exact idempotency key (agent_id + task_id + vendor + amount) with the guarantee that a duplicate returns the original intent. It omits what the caller actually receives back (e.g., an intent ID or status) and whether a 'pause for a human' call blocks or returns immediately.

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 tight sentences, front-loaded with purpose, then decision outcomes, then duplicate handling. No filler and nothing redundant with the schema.

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

Completeness3/5

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

For a 9-parameter, 6-required mutation tool with no output schema, the description covers purpose, policy branches, and idempotency well, but never states the shape of the response or whether the call waits on human review. Those are the details an agent most needs to sequence its next action after calling.

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 coverage is 100%, so the baseline is 3; each parameter is already described in the schema. The description does add one genuine piece of meaning beyond the schema by naming which fields compose the idempotency key, though it says 'vendor' rather than the schema's 'vendor_domain' and leaves behaviorally important fields like is_recurring and alternatives_attempted untouched.

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

Purpose4/5

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

The description gives a specific verb and object — 'Declare a purchase before making it' — which clearly frames this as pre-authorization rather than the actual payment, implicitly separating it from send_payment. It stops short of naming any sibling explicitly, so sibling differentiation is inferred rather than stated.

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

Usage Guidelines4/5

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

The trigger condition is explicit: call this before spending, and policy will auto-approve, pause for a human, or deny. That gives solid context for when to call it, but there is no guidance on what to do after a pause/deny (e.g., poll get_intent_status, retry, or escalate), so the workflow around the tool is only partially covered.

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