MCP Tools as Forms

When building agentic systems, our natural instinct is to give the runtime an all-in-one toolkit. However, when an agent navigates a large list of tools for a simple task, tool-selection accuracy drops, parameter hallucinations increase, and valuable tokens are wasted on irrelevant schemas.

For decades, user experience engineering has focused on structuring visual layouts and forms to reduce friction for humans. In generative AI engineering, we must design for Agent Experience (AX).

The Core Definitions of AX for MCP

To build an optimized Agent Experience, we map our runtime components directly to the layers of a modern software stack:

• The Agent Runtime: The generative system containing one or more MCP clients, working toward a specific operational goal (for example, a Product Development Assistant). It acts as the user interpreting context, filling out forms, and deciding which workflow step to submit next.
• The MCP Server (Application Domain): A distinct, modular capability domain we grant to the agent (such as a Product Registry, Materials Database, or Procurement Service). In AX, this equates to a distinct application view or workspace.
• The Tools (Interactive Forms): The atomic functions exposed by that server to execute a specific workflow step. Each tool is a structured form with a title, helper text, typed input fields, validation rules, and a submit action. Keeping capabilities bounded to explicit forms also eliminates open shell access and provides a clear pane for capability auditing (see Consistent Contracts over Broad Bash).

Monolithic vs. Composable AX

When deciding whether a tool belongs in a specific server, apply the core AX architecture question: "Can this capability exist and provide utility entirely on its own?"

• Monolithic Approach (Fragile AX): Building a single, massive service that handles everything from searching products and analyzing material chemistry to emailing suppliers. While it solves the immediate integration hurdle, it couples the server to one specific agent, floods the attention window with irrelevant schemas, and prevents reuse by future inventory or compliance workflows.

• Composable Approach (Optimized AX): Partitioning the lifecycle into separate, domain-specific capabilities. By keeping products, raw materials, and procurement workflows in independent servers, we create a flexible ecosystem where any agent can mix and match the exact skillsets it needs while maintaining a clean, low-latency interface.

Lifecycle Blueprint Example

If we build an agent to assist a product designer within a Product Lifecycle Management (PLM) application, we cleanly layer three distinct capabilities to keep our tool definitions reusable and dry:

Designing the Agent Form: Names, Descriptions, & Fields

Because the agent relies entirely on semantic understanding to select and fill out tools, our JSON Schema definitions serve as our primary form design. Clear form contracts are the foundation of reliable tool execution.

1. Tool Naming Conventions (Form Title & Submit Label)

• Syntax: Use a clear action_noun format in snake_case.
• AX Guidance: Start with a strong, unambiguous verb (search, get, request). Clear action_noun names act like well-labeled form titles and submit actions, so the model maps the tool name directly to the intended operation. Avoid passive or overly broad verbs like run, process, or do.
• Example: get_bill_of_materials provides immediate clarity compared to bom_fetcher or view_bom.

2. Tool Descriptions (Form Header & Helper Text)

• AX Guidance: Write descriptions directly for the model, not a human developer. State exactly when the form should be used, what context it expects, and what data it returns. Treat this like the header copy at the top of a form that explains its purpose before the user starts typing.
• Fragile AX: "Fetches the BOM for an item."
• Optimized AX: "Use this tool when you need to retrieve the complete hierarchical list of components, materials, and fasteners (our Bill of Materials) required to manufacture a specific product. Requires a valid product ID."

3. Parameter Descriptions (Form Fields & Validation Hints)

• AX Guidance: Detailed parameter descriptions act as field labels, placeholders, and validation hints for the model. Specify data types, expected formats, and whether the field depends on a preceding tool to populate its value.
• Fragile AX: id: "The product id."
• Optimized AX: product_id: "The unique alphanumeric identifier of the product (for example, 'PROD-1024'). This field has a strict sequencing dependency - if you do not know the product_id, submit search_products first."

Complete Form Schema Blueprint (JSON Example)

Here is how the request_sample tool from the Product Sample Server is structured under these AX guidelines, demonstrating how we explicitly define nested fieldsets, defaults, and enum dropdowns for the agent:

{
  "name": "request_sample",
  "description": "Submits a request for a physical product prototype or material sample from a vendor. Use this only after identifying the specific product ID requiring a sample.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "product_id": {
        "type": "string",
        "description": "The unique system identifier for the product (for example, 'PRD-99823') for which a sample is being requested."
      },
      "sample_details": {
        "type": "object",
        "description": "Specific parameters regarding the required prototype layout.",
        "properties": {
          "quantity": {
            "type": "integer",
            "default": 3,
            "description": "The number of sample units requested. Typically defaults to 3."
          },
          "shipping_speed": {
            "type": "string",
            "enum": ["standard", "expedited"],
            "description": "The urgency of the sample delivery. Strongly enforce this restriction."
          }
        },
        "required": ["quantity"]
      }
    },
    "required": ["product_id", "sample_details"]
  }
}

Interactive Simulation: Test Tool Forms in the MCP Tester

For a hands-on demo of how an agent inspects, validates, and submits an MCP tool's contract at runtime (the same way a human views and submits a form), explore our interactive MCP Server Tester. The tester maps JSON Schema definitions into typed form inputs (with enum dropdowns, boolean toggles, and array fieldsets) and live-generates the execution calls so you can invoke a tool the same way the agent does.

Core AX Series Recap

With all four tiers of the core architecture established, you now have the complete blueprint for engineering reliable agent interfaces:

• Part 1: AX Fundamentals - Context as an interface, concept density, and the 3-Tier AX Triad.
• Part 2: Operating Charters - Persistent governance, authority boundaries, and fallback invariants.
• Part 3: Context Documents - Markdown SOPs, onboarding docs, and on-demand domain rules.
• Part 4: MCP Tools as Forms (Current) - Single Capability Principle, composable servers, and typed form affordances.