Tools and mappings

A tool is one action an agent can take, such as search_customers or create_invoice. PipMCP generates tools from your API's operations, and you stay in control of what they are called, what they do and whether agents can see them.

How operations become tools

1. Structure. Every operation is analysed: method, path, parameters, request and response schemas, operation ID and tags.
2. Meaning. PipMCP maps each operation to a business resource (customer, invoice, order…) and an action (list, search, get, create, update, delete, send, refund…). Deterministic rules and learned patterns run first; an AI model helps with the rest, using only the API definition.
3. Confidence. Each mapping gets a confidence score. Confident mappings are accepted; uncertain ones are marked Needs review.
4. Compilation. Each mapped action becomes a tool with a name, a description, a flat input schema and an execution plan.

Naming

Tool names follow a verb-noun pattern in snake_case, derived from the mapped action and resource:

Action	Example
list	list_invoices
search	search_customers
get	get_customer
create	create_customer
update	update_order
delete	delete_customer
nested collection	list_customer_addresses
other actions	send_invoice, refund_payment

Names are at most 64 characters. Descriptions are at most 600 characters and are checked for text that reads like instructions to an agent; such text is removed so an imported spec cannot steer the model.

Reviewing a new import

On the version review screen:

• Needs review items are operations or resources PipMCP was unsure about. Confirm the suggestion or pick the right resource and action. Publishing is blocked while uncertain mappings remain.
• Failing tools did not pass their quality checks. Fix or disable them before publishing.
• Every mapping shows its source: Rule, Learned pattern, Depaza (AI-assisted) or Human.

Your corrections are recorded. When the same correction is confirmed repeatedly across imports, it becomes a learned pattern that is applied automatically next time.

Editing a tool

Open a tool to change:

• Display name and description.
• Risk level (0–4). See Permissions and risk.
• Confirmation: policy (follow the endpoint's rules, the default), always (always ask) or never (skip confirmation; ignored for risk level 3 and above).
• Visibility: enabled or disabled. Disabled tools are never exposed.
• Input schema and execution plan (Pro plan and above).

Every edit creates a new tool version, runs the static tests and quality checks again, and must be published before agents see it. You can also run a live test against a connection; write operations are only executed in a live test when you explicitly allow it. Live tests do not count toward usage.

Execution plans

Behind every tool is a JSON execution plan. Most tools have one step; a plan can have up to 10 steps, each calling one operation of the same API version.

{
  "version": 1,
  "steps": [
    {
      "id": "find_customer",
      "type": "http_operation",
      "operation_id": "<operation id>",
      "input_map": { "query.email": "$input.email" }
    },
    {
      "id": "create_order",
      "type": "http_operation",
      "operation_id": "<operation id>",
      "input_map": {
        "body.customer_id": "$steps.find_customer.response.items[0].id",
        "body.lines": "$input.lines"
      }
    }
  ]
}

• Targets start with path., query., header., body. or form..
• $input.<name> refers to a tool input; $steps.<id>.response… refers to an earlier step's response.
• Every required upstream path, query and header parameter must be mapped.
• Plans are validated when saved. There is no generated code: PipMCP's executor interprets the plan.

One tool call counts as one agent action, however many steps it runs.

Output limits

To keep results useful for a model, responses are normalised:

• Lists are capped at 25 items; pagination information is returned so the agent can ask for more.
• Long strings are truncated at 4,000 characters.
• A single result is capped at 64 KB.

Errors

Upstream failures are mapped to a stable set of codes. Each error has a message, optional details (field-level messages), a suggested_action, retryable and, where known, retry_after_seconds.

Code	Meaning
INVALID_INPUT	The arguments do not match the tool's input schema. Nothing was sent upstream.
VALIDATION_FAILED	The upstream API rejected the request data.
AUTH_FAILED	The upstream API rejected the credentials.
TOKEN_EXPIRED	The OAuth token expired and could not be refreshed. Reconnect the account.
PERMISSION_DENIED	The credentials are valid but not allowed to do this upstream.
NOT_FOUND	The upstream record does not exist.
CONFLICT	The upstream API reported a conflict, e.g. a duplicate.
RATE_LIMITED	The upstream API's rate limit was reached. Retryable.
UPSTREAM_TIMEOUT	The upstream API did not answer in time.
UPSTREAM_UNAVAILABLE	The upstream API could not be reached or returned a server error.
UNEXPECTED_RESPONSE	The upstream response could not be interpreted.
POLICY_DENIED	A policy or preset blocks this action on this endpoint.
CONFIRMATION_REQUIRED	The action needs human approval and was not executed.
BLOCKED_DESTINATION	The request would go to a blocked or private address.
USAGE_LIMIT_REACHED	The workspace has used its agent actions for this period.
CONNECTION_UNAVAILABLE	The connection for this tool is missing or disabled.

Success and failure are always decided deterministically from the upstream response, never by an AI model.