pipehero

add_api_example

Idempotent

Save a response example on an endpoint (for instance the 402 your handler returns for a declined card). Replaces the example with the same name, so it is safe to repeat.

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": {
      "collection_id": "<collection_id>",
      "name": "<name>",
      "status": "<status>"
    },
    "name": "add_api_example"
  }
}

Input Schema

Name	Required	Description
`body`	No	Example response body, any JSON, e.g. {"error": "card_declined"}.
`name`	Yes	e.g. Card declined.
`path`	No	Route path as written in the code, e.g. /v1/charges/:id or /v1/charges/{id}.
`method`	No	HTTP method of the route, e.g. POST. Use with path instead of endpoint_id.
`status`	Yes	HTTP status code of the response, e.g. 402.
`headers`	No	Response headers of the example, e.g. [{"name": "Content-Type", "value": "application/json"}].
`endpoint_id`	No	Id of the endpoint. Alternative to method + path.
`status_text`	No	Reason phrase, e.g. Payment Required.
`collection_id`	Yes	Id from list_api_collections.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 29, 2026

changedInput schema / properties / body / description

Previous value: -"Example response body (any JSON)."New value: +"Example response body, any JSON, e.g. {\"error\": \"card_declined\"}."

addedInput schema / properties / body / type

Added value: +[
+  "object",
+  "array",
+  "string",
+  "number",
+  "boolean",
+  "null"
+]

addedInput schema / properties / headers / description

Added value: +"Response headers of the example, e.g. [{\"name\": \"Content-Type\", \"value\": \"application/json\"}]."

addedInput schema / properties / status / description

Added value: +"HTTP status code of the response, e.g. 402."

addedInput schema / properties / status_text / description
```
Added value: +"Reason phrase, e.g. Payment Required."
```

AddedSep 21, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, and the description reinforces this by explaining the mechanism: same-name examples are replaced, so repeats are safe. It adds a useful behavioral fact but does not cover what happens to other examples on the endpoint or any 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.

Conciseness5/5

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

Two short sentences, the core action is front-loaded, and the second sentence delivers the replace/idempotency fact that an agent actually needs before calling. No filler.

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?

For a 9-param tool with full schema coverage and no output schema, the description covers purpose and write semantics adequately; it could say a bit more about how the example is identified on the endpoint (name uniqueness scope) and what is returned, but nothing essential 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% with per-field examples, so the schema already carries the parameter burden. The description only echoes 'endpoint' and 'name' implicitly and adds no syntax or constraint detail beyond the structured fields, so the baseline 3 applies.

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?

States a specific verb and resource ('Save a response example on an endpoint') and illustrates with a concrete case (a 402 declined-card response). It is clearly distinct from sibling tools like upsert_api_endpoint or save_captured_request, but never names those neighbors to reinforce the distinction.

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

Usage Guidelines3/5

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

The example scenario implies when the tool is useful (documenting non-2xx responses), but there is no explicit when-to-use/when-not framing and no mention of the endpoint_id vs method+path alternatives, which are real routing decisions an agent must make.

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

All pipehero tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.