Agent Network Best Practices

general > limit-agent-tools

Guidance

This rule validates that external agents don't have more than 10 MCP (Model Context Protocol) tools in their metadata configuration. MCP tools provide agents with specific capabilities and functions. Excessive tool definitions lead to management complexity, performance issues, and agent designs that try to do too much. Limiting tool count enforces focused agent design where each agent has a clear, manageable set of capabilities instead of an overly broad tool aggregator. This constraint requires better separation of concerns and maintains agent performance by preventing tool overload that slows down agent initialization, reasoning, and execution. The rule applies to external agent metadata configurations in Agent Network specifications. It provides an architectural guideline for maintainable, performant agent networks with clearly scoped responsibilities.

Message

Agent 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
agents:
  customer-service-agent:
    metadata:
      platform: agentforce
      protocol: a2a
      # 3 MCP tools - within 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
        - mcp:
            ref:
              name: notification-mcp
            allowed:
              - NotificationMcp.send_email

invalid

schemaVersion: 1.0.0
agents:
  customer-service-agent:
    metadata:
      platform: agentforce
      protocol: a2a
      # 12 MCP 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

Applies to metadata

Constraint

Type: Declarative Validation