pipehero

upsert_api_endpoint

Idempotent

Document an endpoint: creates it, or updates the existing one for the same method + path. Use it whenever you add or change a route in the code, so the docs stay true. Only the fields you send change. path may use :id, {id} or {{id}} for variables. folder is created by name if missing. Send version (from get_api_endpoint) to avoid overwriting a teammate's edit; a stale version is rejected.

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>",
      "method": "<method>",
      "path": "<path>"
    },
    "name": "upsert_api_endpoint"
  }
}

Input Schema

Name	Required	Description
`body`	No	Example request body, any JSON, e.g. {"amount": 1000}. null clears it.
`kind`	No	`event` for a webhook your app sends.
`name`	No	Short title, e.g. Create a charge. Defaults to METHOD /path.
`path`	Yes	Route path as written in the code, e.g. /v1/charges/:id or /v1/charges/{id}.
`folder`	No	Folder name, e.g. Charges.
`method`	Yes	HTTP method, e.g. POST. For an `event`, the method it is delivered with.
`params`	No	Documented fields.
`headers`	No	Request headers to send, e.g. [{"name": "Authorization", "value": "Bearer {{token}}"}].
`version`	No	The endpoint's `version` from get_api_endpoint. Omit for a new endpoint.
`description`	No	What the endpoint does and when to call it.
`collection_id`	Yes	Id from list_api_collections.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 29, 2026

changedInput schema / properties / body / description

Previous value: -"Example request body (any JSON). null clears it."New value: +"Example request body, any JSON, e.g. {\"amount\": 1000}. null clears it."

addedInput schema / properties / body / type

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

addedInput schema / properties / collection_id / description
```
Added value: +"Id from list_api_collections."
```

addedInput schema / properties / description / description

Added value: +"What the endpoint does and when to call it."

addedInput schema / properties / headers / description

Added value: +"Request headers to send, e.g. [{\"name\": \"Authorization\", \"value\": \"Bearer {{token}}\"}]."

addedInput schema / properties / method / description

Added value: +"HTTP method, e.g. POST. For an `event`, the method it is delivered with."

addedInput schema / properties / path / description

Added value: +"Route path as written in the code, e.g. /v1/charges/:id or /v1/charges/{id}."

addedInput schema / properties / version / description

Added value: +"The endpoint's `version` from get_api_endpoint. Omit for a new endpoint."

AddedSep 21, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Beyond the annotations (idempotent, non-destructive), the description discloses partial-update semantics, folder auto-creation by name, and optimistic concurrency (stale version rejected) – real behavioral context an agent can't see in the schema. It doesn't say what the upsert returns or how a kind/method mismatch is resolved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

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

The identity of the tool and its upsert key are front-loaded, and each following sentence carries a distinct rule (partial update, path syntax, folder creation, version conflict). Slightly dense for five clauses, but nothing is 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 an 11-parameter mutation with no output schema, the description covers the conflict risk, default behaviors, and the trickiest field formats. Only the return value and any constraints on changing collection_id are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/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; the description earns above that by explaining path-variable syntax (:id, {id}, {{id}}), that `folder` is created if missing, that `version` must come from get_api_endpoint, and that only sent fields are changed.

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?

"Document an endpoint: creates it, or updates the existing one for the same method + path" gives a specific verb pair, resource, and the upsert key, which immediately separates it from create_api_collection, get_api_endpoint, and delete_api_endpoint.

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?

It says when to use it ("whenever you add or change a route in the code") and points at the read-side sibling by naming get_api_endpoint as the source of `version`. It stops short of explicit exclusions, e.g. when to edit via a proposal or when import_api_spec is the better path.

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.