Three tools with basic definitions and schemas present. Tool names follow verb_noun convention (contar_*, buscar_*) but descriptions are minimal and lack actionable guidance for LLM selection. Input schemas are properly typed but lack constraints (enums, ranges). Output schemas are documented in code but return unstructured dict responses. No error handling guidance. Security: no secrets exposed, but no audit logging. Resources feature present but undocumented. Overall: serviceable for simple read-only queries but missing production-grade polish around error recovery, schema completeness, and discovery patterns.

• Add formal output schema documentation. E.g., 'Returns: {total_clientes: int, filtro_bairro: str|null}' and for search results: '{termo_busca: str, resultados_encontrados: int, clientes: [{id: int, nome: str, email: str, telefone: str, bairro: str, endereco: str}], next_cursor?: str}'.
• Implement pagination for list results. Add limit (default 20, max 100) and offset/cursor parameters to search tools. Return total_count or next_cursor to enable multi-page results.
• Expand tool descriptions to 100-150 chars following: '[Action]. [When to use vs. similar tools]. [Typical return structure]. [Error cases].' Example: 'Search clients by exact bairro name. Use buscar_cliente_por_nome for partial name matches. Returns up to 20 results with client details. Returns empty list if no matches found.'
• Document error cases in descriptions: 'If bairro is empty string, returns error dict with {erro: 'Bairro não fornecido', clientes: []}. Try providing a valid neighborhood name.'
• Add resource description to server metadata: '@mcp.resource("clientes://estatisticas") returns summary statistics (total_clientes, clientes by bairro). Call this to understand data distribution before detailed searches.'
• Clarify search behavior: 'Uses case-insensitive LIKE matching. 'silva' matches 'Silva', 'SILVA', and substrings like 'silvana'. Wildcards not supported.'
• Consider adding a list_bairros discovery tool to help LLMs understand available neighborhoods before filtering.
• Validate parameters early and return actionable errors. E.g., if nome is empty, return {erro: 'nome required and must be non-empty string', hint: 'Try buscar_cliente_por_nome(nome="silva")'} instead of silent error dict.