# BRAINIAC Agent Tool Schema Description Scorer

> BRAINIAC Agent Tool Schema Description Scorer is a paid API for AI agents from www.brainiac.software, paid per call via x402, $0.03/call, status unknown (last checked 2026-11-12).

Scores and validates AI agent tool schema descriptions for quality, flagging missing purpose, inputs, outputs, and usage guidance

## Facts

- Endpoint: POST https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-description-score?utm_source=zero.xyz
- Price: $0.03/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-12
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/brainiac-agent-tool-schema-description-scorer-c1b1f4a1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_0pwuK3RB64bws8WjY2EsI

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability brainiac-agent-tool-schema-description-scorer-c1b1f4a1 -d '<json body>'
```

Example prompt: Can you score the quality of my agent tool description? The tool is called 'get_weather' and its description is 'Returns current weather for a city. Pass a city name as input. Returns temperature and conditions. Use when you need live weather data.'

## When to prefer this

Use this endpoint when you need a fast, deterministic, heuristic-based quality score for agent tool schemas — particularly before publishing or deploying tools to an agent marketplace. Prefer this over manual review when you need structured, machine-readable feedback at scale. It is especially useful for CI/CD pipelines validating tool documentation quality. Not suited for semantic correctness checks or natural language quality judgments beyond phrase matching.

## Known failure modes

- Malformed JSON in tools array returns validation error
- Tool name missing or empty causes schema rejection
- More than 80 tools submitted exceeds maxItems limit
- Very long descriptions exceeding 8000 characters are truncated or rejected
- Score reflects only phrase-matching heuristics, not semantic accuracy — a technically correct but differently phrased description may score poorly
- Schema references via $ref to external URLs are not fetched and will not resolve

## How this service works

Pay-per-call APIs for AI agents: OFAC sanctions screening, compliance checks, token security, and Base chain data via x402. No account. Fixed USDC price. MCP-ready.

## Output

Returns a numeric score (0–100) representing average description quality across all submitted tools, plus a list of issues (with severity, location, type, and suggested fix), warnings for missing input/output documentation, recommendations for usage guidance, an analysis summary string, and a list of checker limitations.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "tools": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "name"
    ],
    "properties": {
     "name": {
      "type": "string",
      "maxLength": 160,
      "minLength": 1
     },
     "examples": {
      "type": "array",
      "items": {},
      "maxItems": 10
     },
     "parameters": {
      "type": "object",
      "propertyNames": {
       "type": "string",
       "maxLength": 80
      },
      "additionalProperties": {}
     },
     "description": {
      "type": "string",
      "maxLength": 8000
     },
     "inputSchema": {
      "type": "object",
      "propertyNames": {
       "type": "string",
       "maxLength": 80
      },
      "additionalProperties": {}
     },
     "outputSchema": {
      "type": "object",
      "propertyNames": {
       "type": "string",
       "maxLength": 80
      },
      "additionalProperties": {}
     }
    },
    "additionalProperties": false
   },
   "maxItems": 80
  },
  "openapi": {
   "type": "object",
   "propertyNames": {
    "type": "string",
    "maxLength": 80
   },
   "additionalProperties": {}
  },
  "schemas": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "name",
     "schema"
    ],
    "properties": {
     "name": {
      "type": "string",
      "maxLength": 160,
      "minLength": 1
     },
     "schema": {
      "type": "object",
      "propertyNames": {
       "type": "string",
       "maxLength": 80
      },
      "additionalProperties": {}
     }
    },
    "additionalProperties": false
   },
   "maxItems": 80
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "score": 58,
  "issues": [
   {
    "type": "unclear_purpose",
    "evidence": "Search stored orders.",
    "location": "tools[0]",
    "severity": "medium",
    "description": "The description is missing or shorter than 40 characters, so an agent may not know the tool's purpose.",
    "suggested_fix": "Write at least 40 characters that state what the tool does."
   }
  ],
  "success": true,
  "analysis": "Scored 2 descriptions. The score is the average of the per-tool checks.",
  "warnings": [
   {
    "type": "inputs_not_stated",
    "location": "tools[0]",
    "description": "The description does not mention inputs and no property has a description."
   },
   {
    "type": "outputs_not_stated",
    "location": "tools[0]",
    "description": "The description does not mention a result and no output schema was supplied."
   }
  ],
  "limitations": [
   "Checks use the supplied JSON only. No schema URL is fetched and no model reads the text.",
   "Supported dialects for keyword checks are JSON Schema draft-07, JSON Schema 2020-12, OpenAPI 3.0, and OpenAPI 3.1. Other drafts are reported only when a keyword is on the target ban list.",
   "Example validation understands type, enum, const, properties, required, additionalProperties as a boolean, items, numeric and length bounds, and anyOf, oneOf, and allOf. A $ref is resolved only inside the same document at #/$defs, #/definitions, or #/components/schemas.",
   "Purpose requires a description of at least 40 characters that is not the tool name. Inputs match input, parameter, provide, accepts, or pass, or a property description. Outputs match return, output, result, or responds, or an output schema. Usage matches use when, when the, call this, or do not use.",
   "These are phrase checks. They do not judge whether the description is true.",
   "Missing purpose subtracts 30. Missing inputs or outputs subtract 20 each. Missing usage subtracts 15. The reported score is the average across tools."
  ],
  "recommendations": [
   {
    "type": "usage_not_stated",
    "location": "tools[0]",
    "description": "The description has no phrase such as use when or do not use."
   }
  ]
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/brainiac-agent-tool-schema-description-scorer-c1b1f4a1/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from www.brainiac.software](https://www.zero.xyz/host/www.brainiac.software/llms.txt)
