AX: Structuring MCP Servers

When building agentic systems, our natural instinct is to provide the runtime with a comprehensive, all-in-one toolkit. However, presenting an agent with too many tools at once introduces unnecessary cognitive load. When an agent has to navigate a large, complex list of tools for a simple task, tool-selection accuracy drops, parameter hallucinations increase, and valuable token budget is wasted on schemas irrelevant to the active objective.

For decades, user experience engineering has focused on structuring visual layouts 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 coordinator, interpreting context and selecting which tool to invoke 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 page layout.
• The Tools (Interactive Components): The atomic functions exposed by that server to execute a specific workflow step. These function as the forms, action modals, and setup wizards the agent interacts with.

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 Interface: Names, Descriptions, & Parameters

Because the agent relies entirely on semantic understanding to select and execute tools, our schema definitions serve as our primary interface design. Clear schemas are the foundation of reliable tool execution.

1. Tool Naming Conventions (Semantic Contrast)

• Syntax: Use a clear action_noun format in snake_case.
• AX Guidance: Start with a strong, unambiguous verb (search, get, request). Clear actions act like high-contrast buttons in a traditional UI, helping the model immediately recognize the function's purpose. 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 (Contextual Microcopy)

• AX Guidance: Write descriptions directly for the model, not a human developer. State exactly when the tool should be invoked, what context it expects, and what data it returns. Treat this like the helper text at the top of a form or onboarding instructions given to a new team member.
• 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 (Sequence Guardrails)

• AX Guidance: Detailed parameter descriptions act as input constraints for the model. Specify data types, expected formats, and whether the parameter connects to a preceding tool for ordered execution.
• Fragile AX: id: "The product id."
• Optimized AX: product_id: "The unique alphanumeric identifier of the product (for example, 'PROD-1024'). This parameter has a strict sequencing dependency; if you do not know your product_id, use our search_products tool first."

Complete 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 complex payloads and strict validation enums 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"]
  }
}

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: Intro to Agent Experience Design - Context as an interface, concept density, and the 3-Tier AX Triad.
• Part 2: AX: System Instructions as Operating Charters - Persistent governance, authority boundaries, and fallback invariants.
• Part 3: AX: Context Documents (SKILL.md) as Interface Page Copy - On-demand domain SOPs, proactive frontmatter, and positive constraints.
• Part 4: AX: Structuring MCP Servers as Action Buttons (Current) - Single Capability Principle, composable servers, and typed form affordances.