Agent Network Best Practices

general > card-description-required

Guidance

This rule validates that every agent card includes a meaningful, nonempty description property. Agent descriptions provide essential documentation for users, administrators, and other systems to understand the agent's purpose, capabilities, and intended use cases. Without a clear description, agents are difficult to discover, evaluate, and integrate within larger agent networks. Effective descriptions help agents quickly find and select the appropriate actions for specific tasks. This rule applies to all agent cards in broker definitions and external agent declarations. It ensures that every agent in the network is documented and that its functionality is transparent to all participants.

Message

Agent Card must include a meaningful description property. Add a clear, non-empty description that explains the agent's purpose, capabilities, and intended use cases to help users understand its functionality.

Examples

valid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "My Broker"
      description: "A sample broker that coordinates agent activities and provides weather information"
      url: "https://my-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "coordination"
          name: "Agent Coordination"
          description: "Coordinates agent activities"
          tags: ["coordination"]
    spec:
      llm:
        ref:
          name: "openai-llm"
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a helpful assistant"
      links:
        - agent:
            ref:
              name: "external-agent"

invalid

schemaVersion: 1.0.0
brokers:
  my-broker:
    card:
      protocolVersion: "0.3.0"
      name: "My Broker"
      # Missing description property - this should trigger the validation rule
      url: "https://my-broker.example.com"
      version: "1.0.0"
      provider:
        organization: "Example Corp"
        url: "https://example.com"
      capabilities:
        streaming: false
        pushNotifications: false
        stateTransitionHistory: false
        extensions: []
      defaultInputModes:
        - "application/json"
      defaultOutputModes:
        - "application/json"
      skills:
        - id: "coordination"
          name: "Agent Coordination"
          description: "Coordinates agent activities"
          tags: ["coordination"]
    spec:
      llm:
        ref:
          name: "openai-llm"
        configuration:
          model: "gpt-4"
      instructions:
        - "You are a helpful assistant"
      links:
        - agent:
            ref:
              name: "external-agent"

Applies to card

Constraint

Type: Declarative Validation