A Model Context Protocol (MCP) server for Norman Finance API providing tools for managing clients, invoices, transactions, taxes, documents, and company information
Norman MCP has 22 well-structured tools with consistent naming (verb_noun pattern) and complete input schemas. All tools have descriptions and parameters are typed with enums where appropriate. However, descriptions are often generic (avg ~60 chars, below the 194-char baseline), lack actionable context for LLM selection, and output schemas are not documented. Error handling is absent, no recovery guidance, retryability classification, or validation feedback. Missing tool annotations (readOnlyHint, destructiveHint) despite clear risk levels. Composition is sound (single responsibility per tool), but descriptions don't explain WHEN to use each tool vs. similar ones (e.g., list_transactions vs. get_transaction).
Create a new client
Create a new invoice
Create a new transaction in Norman Finance
Delete a client
Delete a document
Delete a transaction
Get details of a specific client
Get details about the current company
Descriptions lack actionable context. Most are 30 - 60 chars (e.g., 'Create a new transaction in Norman Finance'). LLMs cannot distinguish when to call create_transaction vs. update_transaction or why. Descriptions should explain prerequisites, expected outcomes, and when to use this tool instead of similar ones.
No output schemas documented. Tools return data but LLMs cannot plan downstream calls without knowing response structure. E.g., does list_transactions return transaction_id, transaction.id, or txn_id? This forces LLMs to guess field names.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 50 | <=2025-11-25 | v2 |
Get details of a specific document
Get details of a specific invoice
Get details of a specific tax report
Get details of a specific transaction
List clients with optional filtering and pagination
List documents with optional filtering
List invoices with optional filtering and pagination
List tax reports available for the user's company
List transactions with optional filtering and pagination
Send an invoice to a client via email
Submit a tax report to Finanzamt
Update an existing client
Update an existing transaction
Upload a document (invoice, receipt, contract, etc.)
No error handling or recovery guidance. Tools lack descriptions of failure modes, retryability, or actionable error messages. E.g., if create_transaction fails due to invalid category, the LLM has no guidance on valid categories or how to recover.
Missing tool annotations. Destructive tools (delete_transaction, delete_client, delete_document) and write tools lack readOnlyHint/destructiveHint/idempotentHint annotations. LLMs cannot distinguish safe reads from irreversible operations without explicit hints.
Parameter descriptions lack format/constraint details. E.g., 'date' params say 'YYYY-MM-DD format' but don't specify if past dates are allowed, if future dates are required, or what happens if the date is invalid. LLMs cannot validate inputs without explicit constraints.