Loading ToolBench
MCP server for managing a books database with CRUD operations via MariaDB
The booksAPI server exhibits foundational tool structure but falls well below production quality. Tool names start with Portuguese verbs (criar, consultar, atualizar, remover) which is acceptable but non-standard in English-first ecosystems. All 5 tools have descriptions and schemas, but descriptions are generic API endpoint summaries (10-25 chars) that lack LLM-optimized context. Parameter descriptions are entirely absent, the 'id' and 'livro' parameters have no documentation explaining their purpose, constraints, or relationships. Output schemas are not documented; callers cannot predict the structure of return values (e.g., does consultar_livros return fields [id, title, author, year_published] or something else?). Error handling exists (try/except with HTTPException) but error responses are generic API errors with no recovery guidance for agents. No input validation beyond Pydantic type checking, no enums, no ranges, no format constraints. The tool composition is reasonable (5 separate operations for CRUD), but lacks idempotency hints and confirmation patterns for destructive operations (remover_livro_api deletes without safeguards).
Endpoint para atualizar um livro no banco de dados.
Endpoint para consultar todos os livros no banco de dados.
Endpoint para adicionar um novo livro ao banco de dados.
Endpoint para obter a quantidade de livros no banco de dados.
Endpoint para remover um livro no banco de dados.
Tool descriptions are too short and lack LLM optimization. Descriptions like 'Endpoint para adicionar um novo livro ao banco de dados.' (10-25 chars) fall far below the 50-200 char baseline for production tools and provide minimal context for agent tool selection.
Input parameters lack descriptions entirely. The 'id' parameter in atualizar_livro_api and remover_livro_api has a description, but 'livro' object in criar_livro and atualizar_livro_api has no description. Nested object properties (title, author, year_published) are completely undocumented. LLMs cannot infer parameter meaning from names alone.
Output schemas are not documented. Tools return dict, list[dict], or other structures with no schema documentation. For example, criar_livro returns {"mensagem": str}, but this is not declared. LLMs cannot plan downstream tool calls or parse responses without knowing field names and types.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 42 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
No input validation or constraint documentation. Parameters accept any integer (id) or string (title, author) with no range, format, or enum constraints. No documentation of what happens if id does not exist, or if title/author are empty.
Error messages do not guide agent recovery. Errors like 'Erro ao adicionar o livro: {e}' expose raw database exceptions and offer no actionable next step (e.g., 'Try again' or 'Check the input format'). Agents cannot self-correct without explicit guidance.
Destructive operation (remover_livro_api) lacks confirmation or dry-run pattern. An agent can delete a book with a single call and no confirmation step, risking accidental data loss. No idempotent hint or warning in the tool definition.
Tool names are non-standard. Portuguese verbs (criar, consultar, atualizar, remover) are not aligned with English-first tooling conventions (create, list, update, delete). This increases cognitive load for English-speaking LLMs and violates the pattern baseline of verb_noun naming in English.
Tool name inconsistency: 'atualizar_livro_api' and 'remover_livro_api' include '_api' suffix, while 'criar_livro', 'quantidade_livros', and 'consultar_livros' do not. Inconsistent naming violates the principle that tools operating on the same resource must have obvious, consistent naming.