Skip to main content
The ValidationResult model contains the outcome of validating an AGENTS.md file, including any errors, warnings, and optional endpoint reachability checks.

​
Fields

​
valid
boolean
required
Whether the AGENTS.md file passed validation. true if the file is valid with no errors, false if there are validation errors.
​
errors
array
required
An array of error messages describing validation failures. Empty if the file is valid.Each item is a string describing a specific validation error, such as:
  • Missing required fields
  • Invalid data types
  • Malformed JSON schemas
  • Incorrect file structure
​
warnings
array
required
An array of warning messages for non-critical issues. The file can still be valid even with warnings.Warnings might include:
  • Missing optional but recommended fields
  • Formatting inconsistencies
  • Deprecated patterns
  • Best practice suggestions
​
endpoint_results
array
default:"[]"
Results from checking the reachability of endpoints declared in the AGENTS.md file. Only populated when using the --check-endpoints flag.

​
Examples

​
Valid AGENTS.md

{
  "valid": true,
  "errors": [],
  "warnings": [
    "Consider adding rate_limits information",
    "Contact information is missing"
  ],
  "endpoint_results": []
}

​
Invalid with Errors

{
  "valid": false,
  "errors": [
    "Missing required field: name",
    "Missing required field: description",
    "Invalid capability schema: input_schema must be a valid JSON object"
  ],
  "warnings": [],
  "endpoint_results": []
}

​
With Endpoint Checks

{
  "valid": true,
  "errors": [],
  "warnings": [
    "Version field is recommended but not required"
  ],
  "endpoint_results": [
    {
      "endpoint": "GET /health",
      "reachable": true,
      "status_code": 200,
      "error": null
    },
    {
      "endpoint": "POST /api/tasks",
      "reachable": true,
      "status_code": 401,
      "error": null
    },
    {
      "endpoint": "GET /api/stats",
      "reachable": false,
      "status_code": null,
      "error": "Connection refused (port 8080 not open)"
    }
  ]
}

​
Usage

The ValidationResult is returned by:

​
CLI Validation

# Basic validation
beacon validate ./AGENTS.md

# Validation with endpoint checks
beacon validate ./AGENTS.md --check-endpoints

​
API Endpoint

# POST /validate
curl -X POST http://localhost:8080/validate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# AGENTS.md\n\n...",
    "provider": "beacon-ai-cloud"
  }'

​
Interpreting Results

  • valid: true, no errors: The AGENTS.md file is well-formed and complete
  • valid: false, with errors: Critical issues prevent the file from being used by agents
  • warnings present: The file is usable but could be improved
  • endpoint_results: Shows whether declared endpoints are actually accessible (useful for CI/CD validation)

Build docs developers (and LLMs) love

Get started for freeTalk to us