{"uid":"cap_-BMkggKV36qT4uJ2VlUWg","slug":"brainiac-agent-tool-schema-ambiguity-detector-091ec0dc","name":"BRAINIAC Agent Tool Schema Ambiguity Detector","description":"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.","url":"https://www.brainiac.software/api/v1/agent-tool-schema/tool-schema-ambiguity-detect?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"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}}},"responseSchema":{"type":"json","example":{"score":61,"issues":[{"type":"generic_tool_name","evidence":"run","location":"tools[0]","severity":"medium","description":"The tool name is a generic verb, so an agent cannot tell when to select it.","suggested_fix":"Use a name that states the object and the action, such as search_orders."},{"type":"description_repeats_name","evidence":"run","location":"tools[0]","severity":"medium","description":"The description repeats the tool name and adds no selection guidance.","suggested_fix":"Describe the purpose, the input, and when the tool should be used."},{"type":"generic_parameter","evidence":"data","location":"tools[0].parameters.properties.data","severity":"medium","description":"A parameter name does not say what the agent should put in it.","suggested_fix":"Rename the parameter to the value it holds, such as email or order_id."},{"type":"confusable_name","evidence":"SearchOrders and search_orders","location":"tools[1] and tools[2]","severity":"high","description":"These names differ only by case or punctuation, so an agent can select the wrong tool.","suggested_fix":"Give each tool a distinct name after punctuation is removed."}],"success":true,"analysis":"Checked 3 tools for generic names, thin descriptions, and generic parameter names.","warnings":[],"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."],"recommendations":[{"type":"parameter_without_description","location":"tools[0].parameters.properties.data","description":"Parameter data has no description."}]}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.03","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.03/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.03","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.03","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_uj26cxaIb3J4CVqYjzloy","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.03","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Analyzes AI agent tool schemas for naming ambiguity, generic descriptions, and confusable parameters that would cause an agent to misroute or misuse tools","exampleAgentPrompt":"Can you check my agent tools for ambiguity issues? Here are three tools: 'run' with no description, 'SearchOrders' that searches customer orders, and 'search_orders' that searches inventory — flag anything that would confuse an AI agent trying to pick the right tool.","exampleUseCases":[{"title":"Audit MCP toolset before deployment","prompt":"I have a set of 12 MCP tools I'm about to deploy to production — can you run them through the ambiguity detector and tell me which ones have names or descriptions that would trip up an AI agent trying to select the right one?"},{"title":"Debug agent tool misrouting","prompt":"My AI agent keeps calling the wrong tool — I think the tool names might be too generic or confusable. Can you analyze this list of tool definitions and give me a score plus specific fixes for anything that looks ambiguous?"},{"title":"Review OpenAPI spec for agent clarity","prompt":"I have an OpenAPI spec for my API that I want agents to use as tools. Can you check it for generic parameter names, thin descriptions, and any tool names that look too similar to each other, and suggest how to fix them?"}],"resultDescription":"Returns a numeric ambiguity score (0-100), a list of detected issues each with type, evidence, location, severity, description, and suggested fix, a natural-language analysis summary, any warnings, and a list of limitations of the check. Issue types include generic tool names, description-repeats-name, generic parameters, and confusable names.","failureModes":["Malformed input JSON causes validation error","Tools array exceeds 80-item limit","Tool name or description exceeds character limits","Schema $ref resolution fails for external references","Non-standard JSON Schema dialects may not be fully analyzed","Empty or missing tool names rejected by schema validation"],"whenToPreferThis":"Use this endpoint when you need automated, deterministic checks on agent tool schemas before deployment or during CI/CD — especially when you suspect generic names, thin descriptions, or confusable tool pairs are causing an agent to misroute. It is cheaper and faster than an LLM review for structural issues. Prefer it over manual review when you have many tools to audit at once.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-11-11T12:01:02.460Z","isFirstParty":false,"canonicalSlug":"brainiac-agent-tool-schema-ambiguity-detector-091ec0dc"}