Agent Network Best Practices

general > limit-broker-tools

Guidance

This rule validates that brokers don't have more than 10 MCP (Model Context Protocol) tools in their specification. Brokers coordinate agent activities and access orchestration tools. Excessive tool availability leads to complex decision-making processes, performance degradation, and brokers that try to do too much directly instead of delegating to specialized agents. Limiting broker tools enforces separation of concerns where brokers focus on orchestration and coordination while delegating specialized tasks to linked agents. This constraint maintains broker performance by preventing tool overload that slows down the orchestration reasoning process. It also requires an architecture where tool capabilities are distributed across agents instead of centralized in brokers. The rule applies to broker specifications in Agent Network definitions. It provides an architectural guideline for maintainable, performant orchestration patterns.

Message

Broker has too many MCP tools defined. Limit the number of MCP tools to 10 or fewer to maintain optimal performance and reduce management complexity.

Examples

valid

schemaVersion: 1.0.0
brokers:
  customer-service-broker:
    card:
      protocolVersion: "0.3.0"
      name: "Customer Service Broker"
      description: "Coordinates customer service operations with limited tools"
      url: "https://customer-service-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Customer Solutions Inc"
        url: "https://customer-solutions.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "customer-service"
          name: "Customer Service"
          description: "Handles customer service operations"
          tags: ["customer-service", "support"]
    spec:
      llm:
        ref:
          name: my-openai
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a customer service coordinator"
      # 3 tools - within the maxCount: 10 limit
      tools:
        - mcp:
            ref:
              name: customer-service-mcp
            allowed:
              - CustomerServiceMcp.create_ticket
              - CustomerServiceMcp.update_status
              - CustomerServiceMcp.get_customer_info
        - mcp:
            ref:
              name: analytics-mcp
            allowed:
              - AnalyticsMcp.get_analytics
              - AnalyticsMcp.export_reports
        - mcp:
            ref:
              name: notification-mcp
            allowed:
              - NotificationMcp.send_email
              - NotificationMcp.send_sms
llms:
  my-openai:
    kind: openai
    description: "OpenAI GPT-4 model for reasoning"

invalid

schemaVersion: 1.0.0
brokers:
  customer-service-broker:
    card:
      protocolVersion: "0.3.0"
      name: "Customer Service Broker"
      description: "Coordinates customer service operations with too many tools"
      url: "https://customer-service-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Customer Solutions Inc"
        url: "https://customer-solutions.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "customer-service"
          name: "Customer Service"
          description: "Handles customer service operations"
          tags: ["customer-service", "support"]
    spec:
      llm:
        ref:
          name: my-openai
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a customer service coordinator"
      # 12 tools - exceeds the maxCount: 10 limit
      tools:
        - mcp:
            ref:
              name: customer-service-mcp
            allowed:
              - CustomerServiceMcp.create_ticket
              - CustomerServiceMcp.update_status
        - mcp:
            ref:
              name: analytics-mcp
            allowed:
              - AnalyticsMcp.get_analytics
              - AnalyticsMcp.export_reports
        - mcp:
            ref:
              name: notification-mcp
            allowed:
              - NotificationMcp.send_email
              - NotificationMcp.send_sms
        - mcp:
            ref:
              name: integration-mcp
            allowed:
              - IntegrationMcp.sync_data
              - IntegrationMcp.webhook_trigger
        - mcp:
            ref:
              name: database-mcp
            allowed:
              - DatabaseMcp.query
              - DatabaseMcp.insert
        - mcp:
            ref:
              name: file-mcp
            allowed:
              - FileMcp.upload
              - FileMcp.download
        - mcp:
            ref:
              name: email-mcp
            allowed:
              - EmailMcp.send
              - EmailMcp.read
        - mcp:
            ref:
              name: calendar-mcp
            allowed:
              - CalendarMcp.create_event
              - CalendarMcp.list_events
        - mcp:
            ref:
              name: payment-mcp
            allowed:
              - PaymentMcp.process
              - PaymentMcp.refund
        - mcp:
            ref:
              name: inventory-mcp
            allowed:
              - InventoryMcp.check_stock
              - InventoryMcp.update_stock
        - mcp:
            ref:
              name: reporting-mcp
            allowed:
              - ReportingMcp.generate
              - ReportingMcp.export
        - mcp:
            ref:
              name: security-mcp
            allowed:
              - SecurityMcp.authenticate
              - SecurityMcp.authorize
llms:
  my-openai:
    kind: openai
    description: "OpenAI GPT-4 model for reasoning"

Applies to Broker

Constraint

Type: Declarative Validation