Locus

Execute API call

execute

Destructive

Call one enabled endpoint by slug with args from its schema; charges credits. Get the slug from search_apis. max_credits caps the charge. A stable idempotency_key makes retries exactly-once (idempotent_replay:true). Long results continue via get_call_result.

Input Schema

Name	Required	Description
`args`	No	Endpoint args; call describe_api for schema.
`slug`	Yes	provider/endpoint slug.
`loop_id`	No	Agent loop ID when policy requires one.
`attribution`	No	Spend attribution: taskId + feature (+ optional appVersion).
`max_credits`	No	Most credits this call may charge.
`approval_token`	No	From an approval error; send its idempotency_key.
`idempotency_key`	No	Reuse on retry; charges once.

Output Schema

Name	Required	Description
`data`	Yes	Raw provider response.
`usd_charged`	No	USD charged (secret-key auth only).
`credits_balance`	No
`credits_charged`	No
`idempotent_replay`	No	Stored replay; no new charge.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 20, 2026

changedInput schema / properties / approval_token / description

Previous value: -"estimate_cost quote; requires its idempotency_key."New value: +"From an approval error; send its idempotency_key."

addedInput schema / properties / max_credits

Added value: +{
+  "description": "Most credits this call may charge.",
+  "type": [
+    "string",
+    "number"
+  ]
+}

Changed5 schema fields changedOct 7, 2026

changedInput schema / properties / idempotency_key / description

Previous value: -"Stable exactly-once retry key."New value: +"Reuse on retry; charges once."

removedOutput schema / properties / credits_balance / description
```
Removed value: -"Remaining credit balance."
```
removedOutput schema / properties / credits_charged / description
```
Removed value: -"Credits debited for this call."
```

changedOutput schema / properties / data / description

Previous value: -"Raw upstream provider response body."New value: +"Raw provider response."

changedOutput schema / properties / idempotent_replay / description

Previous value: -"True when a stored identical call was replayed; no new charge was made."New value: +"Stored replay; no new charge."

Changed1 schema field changedSep 17, 2026

changedInput schema / properties / args / description

Previous value: -"Endpoint args; schema and example via search_apis or describe_api."New value: +"Endpoint args; call describe_api for schema."

First observedSep 15, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=true, openWorldHint=true), and the description adds real value beyond them: it discloses that the call charges credits, that max_credits caps the charge, and that a stable idempotency_key yields exactly-once retries surfaced as idempotent_replay:true — a conditional idempotency the flat idempotentHint=false cannot express. It omits the approval_token/approval-error flow, which is the one notable behavior left undisclosed.

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?

Four tight clauses, front-loaded with the core action and cost, followed by discovery, cost-cap, idempotency, and continuation. No filler and no repetition of the schema.

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

Completeness4/5

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

With an output schema present, the description needn't explain return values, and it still flags the idempotent_replay field and the long-result handoff. Combined with 100% schema coverage it is nearly complete; the missing piece is any mention of the approval_token / approval-error path, which an agent will only discover from the schema.

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 schema already documents all seven parameters; the description largely restates it (max_credits caps the charge, idempotency_key reused on retry). The only genuinely additive bit is the response field name idempotent_replay:true, which is output-side rather than parameter semantics. Baseline 3 is appropriate.

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?

Specific verb+resource: 'Call one enabled endpoint by slug with args from its schema.' It immediately distinguishes itself from siblings by naming search_apis (for slug discovery) and get_call_result (for continuation). An agent can identify this as the single execution entry point 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.

Usage Guidelines5/5

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

Explicit routing: 'Get the slug from search_apis' tells the agent the prerequisite discovery step, and 'Long results continue via get_call_result' names the follow-up tool. It also states the cost-control condition ('max_credits caps the charge') and the retry condition for idempotency_key, so the when/how is fully specified.

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

All Locus tools Inspect

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.