# Design tool contracts

> Create reusable Menace Voice tools through MCP, attach them by UUID, and preserve a strict boundary between model decisions and system authorization.

{/* Generated by scripts/sync_docs_handbook.mjs from the preserved in-app docs. */}

The Menace Voice MCP server can create reusable HTTP API, end-call, transfer-call, calculator, current-time, and remote MCP-server tools. It does not expose credential secrets. If a new tool needs authentication, a human first creates the credential in the UI; the implementation assistant selects its UUID from list_credentials.

## Specify the behavior before the schema

```text
Business action: read the current status of one customer-owned order
Invoke when: the caller asks about a specific order and confirms the order number
Do not invoke when: the caller asks only about general shipping policy
Input: order_number, string, required, read back once before lookup
Success: return status and estimated_delivery
Not found: verify once, then offer the approved human follow-up
Failure: explain temporary unavailability; do not guess or claim a later retry
```

This contract tells the implementation assistant what schema to create, what node instruction to write, and which runtime scenarios matter. The endpoint must still enforce authentication, ownership, validation, and authorization; a correct model-generated argument is never a substitute for backend checks.

## Use the supported creation flow

- Call list_credentials when authentication is needed and select an existing credential UUID owned by the same organization.
- Call create_tool with the current request schema. Treat created: true and the returned tool_uuid as the only successful creation result.
- Fetch the current workflow with get_workflow_code instead of reconstructing it from memory or from a stale prompt.
- Add the returned UUID to tool_uuids on the specific Start Call or Agent node that needs it.
- Save the complete workflow source with save_workflow and resolve every parse, schema, graph, or tool-name collision error.

## Make HTTP actions safe

- Keep each endpoint single-purpose and validate its request body independently of the model's function schema.
- Return a compact JSON result with stable field names and an explicit empty or error state.
- Use bounded server and downstream timeouts so a slow integration does not stall the conversation indefinitely.
- Make state-changing requests idempotent when retries are possible, and require explicit caller confirmation before irreversible actions.
- Do not put keys, tokens, raw SQL, internal stack traces, or privileged headers in tool descriptions, prompts, or results.

## Scope availability to the conversation stage

A reusable tool exists at workspace level, but the model can call it only when its UUID is attached to the active conversational node. Attach lookup_order to the order-support stage, not every node. For remote MCP servers, also filter the server catalog and select only the remote functions required at that node.

> **Creation is not execution proof**
>
> A created tool and a valid draft prove storage and structural validation. A reviewed run must still show that the right utterance invoked it, the arguments matched the transcript, the endpoint result was handled accurately, and unrelated requests did not invoke it.

Use [Memory and context](/handbook/agents/memory-context) to decide which values belong in the workflow, one run, a document, or an external system.