Agent Tool Schema Intelligence API Documentation

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-lint$0.03 USDC

Lint agent tool schemas

Find malformed JSON Schema and OpenAPI tool definitions in caller-supplied tools: bad types, required names that are not properties, empty enums, and duplicate tool names. Nothing is fetched.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search orders by email.",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "enum": [
              1
            ]
          }
        },
        "required": [
          "email",
          "limit"
        ]
      }
    },
    {
      "name": "search_orders",
      "description": "Search orders again."
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Linted 2 tool or schema definitions.",
  "score": 60,
  "issues": [
    {
      "type": "required_missing_property",
      "severity": "high",
      "description": "A required name is not in properties, so the agent is told to send a field that has no schema.",
      "evidence": "limit",
      "location": "tools[0].parameters.required",
      "suggested_fix": "Add properties.limit or remove limit from required."
    },
    {
      "type": "enum_type_mismatch",
      "severity": "medium",
      "description": "An enum value does not match the declared type, so a correct agent value can still be rejected.",
      "evidence": "[1]",
      "location": "tools[0].parameters.properties.email",
      "suggested_fix": "Make every enum value match type, or change type."
    },
    {
      "type": "duplicate_tool",
      "severity": "high",
      "description": "Two tools share the same name, so an agent cannot choose between them by name.",
      "evidence": "search_orders",
      "location": "tools[0] and tools[1]",
      "suggested_fix": "Rename one tool so each name is unique."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "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.",
    "Local #/ pointers are followed into the supplied schema and OpenAPI document, including $defs, definitions, and components.schemas. External URLs are not.",
    "Score weights: duplicate tool 20, unknown type 15, properties not an object 15, required not an array of strings 15, required name missing 12, array without items 12, empty enum 12, enum type mismatch 8, bound conflict 8, external or non-string $ref 10.",
    "Warnings such as a missing type do not change the score."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-lint" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search orders by email.",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "enum": [
              1
            ]
          }
        },
        "required": [
          "email",
          "limit"
        ]
      }
    },
    {
      "name": "search_orders",
      "description": "Search orders again."
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-ambiguity-detect$0.03 USDC

Detect ambiguous tool schemas

Flag generic tool names, generic parameter names, and descriptions that repeat the name or are missing. Matching is against a fixed word list, not a language model.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "tools": [
    {
      "name": "run",
      "description": "run",
      "parameters": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string"
          }
        }
      }
    },
    {
      "name": "SearchOrders",
      "description": "Search stored orders by the customer email address."
    },
    {
      "name": "search_orders",
      "description": "Search stored orders by the customer email address and return the matching rows."
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked 3 tools for generic names, thin descriptions, and generic parameter names.",
  "score": 61,
  "issues": [
    {
      "type": "generic_tool_name",
      "severity": "medium",
      "description": "The tool name is a generic verb, so an agent cannot tell when to select it.",
      "evidence": "run",
      "location": "tools[0]",
      "suggested_fix": "Use a name that states the object and the action, such as search_orders."
    },
    {
      "type": "description_repeats_name",
      "severity": "medium",
      "description": "The description repeats the tool name and adds no selection guidance.",
      "evidence": "run",
      "location": "tools[0]",
      "suggested_fix": "Describe the purpose, the input, and when the tool should be used."
    },
    {
      "type": "generic_parameter",
      "severity": "medium",
      "description": "A parameter name does not say what the agent should put in it.",
      "evidence": "data",
      "location": "tools[0].parameters.properties.data",
      "suggested_fix": "Rename the parameter to the value it holds, such as email or order_id."
    },
    {
      "type": "confusable_name",
      "severity": "high",
      "description": "These names differ only by case or punctuation, so an agent can select the wrong tool.",
      "evidence": "SearchOrders and search_orders",
      "location": "tools[1] and tools[2]",
      "suggested_fix": "Give each tool a distinct name after punctuation is removed."
    }
  ],
  "warnings": [],
  "recommendations": [
    {
      "type": "parameter_without_description",
      "description": "Parameter data has no description.",
      "location": "tools[0].parameters.properties.data"
    }
  ],
  "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.",
    "Generic tool names are an exact match against tool, run, do, execute, process, handle, get, update, helper, action, and function.",
    "Generic parameters are an exact match against data, value, input, info, item, param, arg, field, obj, payload, and body.",
    "Each confusable name subtracts 15. Each generic name, missing description, repeated description, or generic parameter subtracts 8."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-ambiguity-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tools": [
    {
      "name": "run",
      "description": "run",
      "parameters": {
        "type": "object",
        "properties": {
          "data": {
            "type": "string"
          }
        }
      }
    },
    {
      "name": "SearchOrders",
      "description": "Search stored orders by the customer email address."
    },
    {
      "name": "search_orders",
      "description": "Search stored orders by the customer email address and return the matching rows."
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-overlap-detect$0.04 USDC

Detect overlapping tool schemas

Compare caller-supplied tools for the same name, the same description text, or a very high overlap of longer words. Sharing a few keywords is not treated as a duplicate.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search customer orders by email address and return matching order records.",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          }
        }
      }
    },
    {
      "name": "find_orders",
      "description": "Search customer orders by email address and return matching order records."
    },
    {
      "name": "search_users",
      "description": "Search users by email."
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Compared 3 tools by exact name, exact description, a high word-overlap bar, and identical parameter lists.",
  "score": 80,
  "issues": [
    {
      "type": "identical_description",
      "severity": "high",
      "description": "The descriptions are the same text, so an agent has no way to choose between the tools.",
      "evidence": "search customer orders by email address and return matching order records.",
      "location": "tools[0] and tools[1]",
      "suggested_fix": "State the distinct case for each tool. This is an exact text match, not a keyword overlap."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "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.",
    "A similar description requires at least eight words of length 5 or more on each side, at least five shared words, and a Jaccard ratio of 0.85 or higher.",
    "Sharing keywords below that bar does not create a finding.",
    "Each same name or identical description subtracts 20. Each similar description subtracts 10. Identical parameter lists are warnings and do not change the score."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-overlap-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search customer orders by email address and return matching order records.",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          }
        }
      }
    },
    {
      "name": "find_orders",
      "description": "Search customer orders by email address and return matching order records."
    },
    {
      "name": "search_users",
      "description": "Search users by email."
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-example-validate$0.04 USDC

Validate tool request examples

Check caller-supplied request examples against their JSON Schema types, required fields, enums, and bounds. External schema URLs are not fetched.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "tools": [
    {
      "name": "create_order",
      "description": "Create an order from a sku and a quantity.",
      "parameters": {
        "type": "object",
        "required": [
          "sku",
          "quantity"
        ],
        "additionalProperties": false,
        "properties": {
          "sku": {
            "type": "string",
            "minLength": 2
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "examples": [
        {
          "sku": "A",
          "quantity": 0,
          "note": "rush"
        },
        {
          "sku": "AB",
          "quantity": 1
        }
      ]
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Checked 2 examples. 1 matched the declared schema.",
  "score": 50,
  "issues": [
    {
      "type": "additional_property",
      "severity": "medium",
      "description": "The example includes a field the schema rejects.",
      "evidence": "note",
      "location": "tools[0].examples[0]",
      "suggested_fix": "Remove note or declare it in properties."
    },
    {
      "type": "min_length",
      "severity": "medium",
      "description": "The example is shorter than minLength.",
      "evidence": "1 < 2",
      "location": "tools[0].examples[0].sku",
      "suggested_fix": "Use at least 2 characters."
    },
    {
      "type": "minimum",
      "severity": "medium",
      "description": "The example is below minimum.",
      "evidence": "0 < 1",
      "location": "tools[0].examples[0].quantity",
      "suggested_fix": "Use a number greater than or equal to 1."
    }
  ],
  "warnings": [],
  "recommendations": [],
  "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.",
    "The score is the percentage of examples that produced no schema violation. It is omitted when no example was checked.",
    "A failed $ref that points outside the document is reported and the example is not treated as valid."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-example-validate" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tools": [
    {
      "name": "create_order",
      "description": "Create an order from a sku and a quantity.",
      "parameters": {
        "type": "object",
        "required": [
          "sku",
          "quantity"
        ],
        "additionalProperties": false,
        "properties": {
          "sku": {
            "type": "string",
            "minLength": 2
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "examples": [
        {
          "sku": "A",
          "quantity": 0,
          "note": "rush"
        },
        {
          "sku": "AB",
          "quantity": 1
        }
      ]
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-required-field-audit$0.03 USDC

Audit tool required fields

Find required names that are not properties, repeated required names, and required fields that also declare a default. The audit uses only the supplied schema.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "tools": [
    {
      "name": "create_order",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "default": "NONE"
          }
        },
        "required": [
          "sku",
          "sku",
          "quantity"
        ]
      }
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Audited required arrays on 1 tools.",
  "score": 81,
  "issues": [
    {
      "type": "duplicate_required",
      "severity": "low",
      "description": "The required array lists the same field twice.",
      "evidence": "sku",
      "location": "tools[0].parameters.required",
      "suggested_fix": "List each required field once."
    },
    {
      "type": "required_missing_property",
      "severity": "high",
      "description": "The agent is required to send a field that is not defined.",
      "evidence": "quantity",
      "location": "tools[0].parameters.required",
      "suggested_fix": "Define properties.quantity or stop requiring it."
    }
  ],
  "warnings": [
    {
      "type": "required_has_default",
      "description": "sku is required and also has a default. Agents may disagree about whether to send it.",
      "location": "tools[0].parameters.properties.sku"
    },
    {
      "type": "required_has_default",
      "description": "sku is required and also has a default. Agents may disagree about whether to send it.",
      "location": "tools[0].parameters.properties.sku"
    }
  ],
  "recommendations": [],
  "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.",
    "A missing required property subtracts 15. A duplicate required name subtracts 4. Defaults on required fields and a required list of eight or more are warnings and do not change the score."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-required-field-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tools": [
    {
      "name": "create_order",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "default": "NONE"
          }
        },
        "required": [
          "sku",
          "sku",
          "quantity"
        ]
      }
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-compatibility-check$0.04 USDC

Check tool schema dialect compatibility

Report JSON Schema keywords that the caller-selected dialect does not allow. Targets are draft-07, 2020-12, OpenAPI 3.0, and OpenAPI 3.1. The schema is not sent to a validator service.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object
`target`	Yes	string; One of: draft-07, 2020-12, openapi-3.0, openapi-3.1

Request exampleJSON

{
  "target": "openapi-3.0",
  "tools": [
    {
      "name": "create_order",
      "parameters": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": [
          "string",
          "null"
        ],
        "const": "rush",
        "prefixItems": [
          {
            "type": "string"
          }
        ]
      }
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Compared 1 schemas with openapi-3.0.",
  "score": 44,
  "issues": [
    {
      "type": "unsupported_keyword",
      "severity": "high",
      "description": "prefixItems is not part of openapi-3.0. An agent runtime that only accepts that dialect can reject the tool.",
      "evidence": "prefixItems",
      "location": "tools[0].parameters",
      "suggested_fix": "Remove prefixItems or convert it to a construct openapi-3.0 allows."
    },
    {
      "type": "unsupported_keyword",
      "severity": "high",
      "description": "$schema is not part of openapi-3.0. An agent runtime that only accepts that dialect can reject the tool.",
      "evidence": "$schema",
      "location": "tools[0].parameters",
      "suggested_fix": "Remove $schema or convert it to a construct openapi-3.0 allows."
    },
    {
      "type": "unsupported_keyword",
      "severity": "high",
      "description": "const is not part of openapi-3.0. An agent runtime that only accepts that dialect can reject the tool.",
      "evidence": "const",
      "location": "tools[0].parameters",
      "suggested_fix": "Remove const or convert it to a construct openapi-3.0 allows."
    },
    {
      "type": "type_array",
      "severity": "high",
      "description": "openapi-3.0 expects type to be a single string. An array of types can be dropped or rejected.",
      "evidence": "[\"string\",\"null\"]",
      "location": "tools[0].parameters",
      "suggested_fix": "Use nullable: true instead of a type array that includes null."
    },
    {
      "type": "null_type",
      "severity": "high",
      "description": "OpenAPI 3.0 has no null type. Use nullable instead.",
      "evidence": "null",
      "location": "tools[0].parameters",
      "suggested_fix": "Set nullable: true and remove null from type."
    }
  ],
  "warnings": [
    {
      "type": "dialect_mismatch",
      "description": "$schema says https://json-schema.org/draft/2020-12/schema, which does not name the selected target.",
      "location": "tools[0].parameters"
    }
  ],
  "recommendations": [],
  "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.",
    "The selected target is openapi-3.0. A keyword on that target's ban list subtracts 12. A type-array, null type, or exclusive bound mismatch subtracts 10.",
    "Absence of a finding does not mean the schema is accepted by every agent SDK."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-compatibility-check" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "target": "openapi-3.0",
  "tools": [
    {
      "name": "create_order",
      "parameters": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": [
          "string",
          "null"
        ],
        "const": "rush",
        "prefixItems": [
          {
            "type": "string"
          }
        ]
      }
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-token-cost$0.03 USDC

Estimate tool schema token cost

Estimate tokens for caller-supplied tool names, descriptions, and schemas at four characters per token. The figure is an estimate, not a provider tokenizer count.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search orders by email and return the matching rows for an agent to quote.",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Customer email address."
          }
        }
      }
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Estimated 48 tokens for 1 tools at 4 characters per token. This is an estimate, not an exact tokenizer count. Per tool: search_orders 48.",
  "issues": [],
  "warnings": [],
  "recommendations": [],
  "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.",
    "The estimate is Math.ceil(characters / 4) over the name, description, and JSON text of the input and output schemas.",
    "No score is returned. A character ratio is not a quality grade and is not a provider tokenizer."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-token-cost" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search orders by email and return the matching rows for an agent to quote.",
      "parameters": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Customer email address."
          }
        }
      }
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-description-score$0.03 USDC

Score tool description clarity

Score whether a tool description states a purpose, inputs, outputs, and when to use it. The checks are phrase and length rules, not a language-model reading.

Body

Field	Required	Notes
`tools`	No	array; Array
`schemas`	No	array; Array
`openapi`	No	object

Request exampleJSON

{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search stored orders."
    },
    {
      "name": "create_order",
      "description": "Create an order when the caller provides a sku and quantity. Use when the cart is ready. Returns the new order id.",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Stock keeping unit."
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          }
        }
      }
    }
  ]
}

Response exampleJSON

{
  "success": true,
  "analysis": "Scored 2 descriptions. The score is the average of the per-tool checks.",
  "score": 58,
  "issues": [
    {
      "type": "unclear_purpose",
      "severity": "medium",
      "description": "The description is missing or shorter than 40 characters, so an agent may not know the tool's purpose.",
      "evidence": "Search stored orders.",
      "location": "tools[0]",
      "suggested_fix": "Write at least 40 characters that state what the tool does."
    }
  ],
  "warnings": [
    {
      "type": "inputs_not_stated",
      "description": "The description does not mention inputs and no property has a description.",
      "location": "tools[0]"
    },
    {
      "type": "outputs_not_stated",
      "description": "The description does not mention a result and no output schema was supplied.",
      "location": "tools[0]"
    }
  ],
  "recommendations": [
    {
      "type": "usage_not_stated",
      "description": "The description has no phrase such as use when or do not use.",
      "location": "tools[0]"
    }
  ],
  "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."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-description-score" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "tools": [
    {
      "name": "search_orders",
      "description": "Search stored orders."
    },
    {
      "name": "create_order",
      "description": "Create an order when the caller provides a sku and quantity. Use when the cart is ready. Returns the new order id.",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Stock keeping unit."
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          }
        }
      }
    }
  ]
}
JSON