This MCP server exposes 3 tools for querying Avalara AvaTax via SQL. All three tools are explicitly registered with schemas and descriptions visible in the source code. However, the tool set shows moderate definition quality issues: tool names are clear and action-oriented (get_, run_), but descriptions lack the specificity needed for LLM-driven selection (e.g., no guidance on when to use avatax_get_tables vs avatax_get_columns vs avatax_run_query). Parameter descriptions are generic. Most critically, output schemas are NOT documented, the tools return CSV-formatted text with vague references to 'column headers' but no structured schema definition. Error handling is minimal (raw RuntimeException wrapping). The server reads data from a proprietary connector (AvaTax) through JDBC, so modification is not possible, but this should be stated explicitly in tool descriptions.

• Document complete output schemas as JSON Schema objects. Specify returned fields, types, and meaning for each tool. Example: avatax_get_tables returns {TABLE_CAT: string, TABLE_SCHEM: string, TABLE_NAME: string}, make this explicit.
• Enhance tool descriptions to answer: WHAT does it do? WHEN should I call it? WHAT will I get? Example for avatax_get_tables: 'List all available tables (entities) in the AvaTax data source. Call this first to discover what you can query. Returns table catalog, schema, and name in CSV format. Useful before calling avatax_get_columns or avatax_run_query.'
• Add parameter constraints and optionality to descriptions. Example: 'catalog (string, optional): The database catalog name. Omit if the AvaTax connector uses a single catalog.' and 'table (string, required): The table name to inspect.'
• Implement structured error responses. Instead of throwing RuntimeException, return a CallToolResult with error content that includes: error code, human-readable message, and recovery suggestion. Example: 'Table not found: sales_invoices. Available tables: [list]. Did you mean one of these?'
• Add a result_limit parameter to avatax_run_query (e.g., 1 - 10000, default 1000) to prevent runaway queries. Document the limit in the description.
• Convert CSV output to JSON objects. Instead of 'Table_CAT,Table_Schem,Table_Name\ninvoices,public,invoice_detail', return [{"table_cat": "invoices", "table_schem": "public", "table_name": "invoice_detail"}] so LLMs can parse results without text parsing.