Design tool contracts

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#

Business action: read the current status of one customer-owned orderInvoke when: the caller asks about a specific order and confirms the order numberDo not invoke when: the caller asks only about general shipping policyInput: order_number, string, required, read back once before lookupSuccess: return status and estimated_deliveryNot found: verify once, then offer the approved human follow-upFailure: 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 to decide which values belong in the workflow, one run, a document, or an external system.