A Model Context Protocol (MCP) server that provides tools to query BrasilAPI across different clients and LLMs.
Brasil API MCP Server has 6 tools with consistent naming conventions (all start with action verbs: get_), but significant gaps in parameter descriptions and output schema documentation. All tools use Zod for schema definition which is positive, but schemas are not fully documented for LLM consumption. Description quality is mixed: tool-level descriptions are present but minimal (10-60 chars), and critical parameter descriptions are missing or trivial. The server lacks output schema documentation entirely, LLMs cannot plan downstream operations without knowing response structure. Error handling is basic (try-catch with generic error messages) and provides no recovery guidance. No tool annotations present.
Get information of all banks from Brazil.
Get information from a specific bank given its code. The code from each bank is returned by get_all_banks tool.
Get information about a company given a CNPJ.
Get information about a book given an ISBN.
Get a location data given a CEP (postal code).
Version 2 of get a location data given a CEP (postal code).
No output schema documented for any tool. Tool descriptions state what is returned (e.g. 'location data', 'bank information') but LLMs cannot plan downstream operations without knowing the exact field names, types, and structure. For example, after calling get_postal_code_v1, an agent cannot know whether the response includes 'state', 'province', or 'uf' without trial-and-error.
Parameter 'code' in get_bank_by_code has null description. The JSON shows 'code: z.number(), ...description: null'. LLM cannot infer what code represents without explicit documentation. Should state: 'The bank code (numeric identifier, e.g. 001 for Banco do Brasil). Use get_all_banks to discover available codes.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-21 | F | 46 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 48 | - | v1 |
Tool descriptions are too brief (10-60 chars). Rubric baseline is 194 chars average. Current descriptions lack context for LLM selection: 'Get a location data given a CEP (postal code)' does not explain WHEN to use v1 vs v2, what data fields are returned, or whether CEP format matters (with/without hyphen?). Descriptions should include: what the tool does, when to use it vs similar tools, what format inputs should be, and key output fields.
Error handling provides no recovery guidance. All errors throw generic messages like 'Failed to fetch cep {cep}' or 'Failed to fetch banks' without actionable next steps. Errors should state: (1) what failed, (2) why, (3) what the LLM should try next. E.g. 'Invalid CEP format. CEP should be 8 digits (e.g., 01310100 or 01310-100). If unsure, call get_postal_code_v1 with a different input.'
No input validation or constraints documented. CEP parameters accept any string (z.string() with no .min()/.max()/.regex()). LLM could pass '123' or 'abc' and receive a cryptic API error. Parameters should enforce constraints and reject invalid input early with clear messages. E.g. z.string().regex(/^\d{5}-?\d{3}$/, 'CEP must be 8 digits, optionally with hyphen').
get_all_banks returns all banks without pagination. If Brazil has hundreds of banks, the response could blow the context window. No limit parameter, no total_count, no next_cursor. Description should state a realistic cap: 'Returns up to 500 bank records. Call get_bank_by_code(code) to fetch details for a specific bank.'
No distinction between CEP v1 and v2 in descriptions. Both tools exist (get_postal_code_v1, get_postal_code_v2), but descriptions do not explain why there are two versions or when to use each. v2 says 'Version 2 of get a location data...' but does not state what improved, what fields differ, or which to prefer. LLM will guess.
Tool definitions inferred from Zod schemas, not explicitly visible in tool registration code. The McpToolDefinition type wraps { name, description, params, handler }, but the actual schema transformation from Zod to JSON Schema is not visible in the provided source. Cannot verify that Zod objects are correctly serialized to JSON Schema for the protocol.