# MCP tool design

How BennyBooks shapes MCP tools for clean, token-efficient agent use.

Agents only see tool names, descriptions, and schemas. Vague or bloated surfaces cause wrong calls and wasted context. BennyBooks ships a curated catalog rather than a raw OpenAPI dump.

## Principles

1. Curate ~12 tools — disable redundant operations in your MCP bridge
2. verb_noun names (list_transactions) matching OpenAPI operationId
3. Descriptions cover what, when to use, and when not to use
4. Put constraints in the schema (enums, date format, limits)
5. Lean lists — default limit=50; prefer get_transaction over list_notes
6. Writes are proposals only until a human approves (recorded in Log)
7. Prefer categoryCode over display names
8. x-mcp annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint

## Default expose set

| Tool | Scope | Role |
| --- | --- | --- |
| get_ontology | public | Get ontology |
| list_categories | read | List categories |
| list_transactions | read | List transactions |
| get_transaction | read | Get transaction |
| get_dashboard_summary | read | Dashboard summary |
| search_receipts | read | Search receipts |
| list_connectors | read | List connectors |
| list_pending_proposals | read | List pending proposals |
| propose_categorization | propose-write | Propose categorization |
| propose_journal_entry | propose-write | Propose journal entry |
| propose_receipt_link | propose-write | Propose receipt link |
| attach_note | propose-write | Attach note (proposal) |

## Workflows

- Categorize — list_categories → list_transactions(status=uncategorized) → propose_categorization
- Investigate — get_transaction (notes + receipts) → search_receipts if needed
- Month-end — get_dashboard_summary → chase uncategorized / receipt_missing / proposals / connectors

> **Audit trail.** Propose-write tools are audit-logged. Humans see Approvals for decisions and Log (/log) for history. Agents have no read API for Log in v1 — see Audit Log guide.

> **Source of truth.** lib/mcp/tool-catalog.ts drives OpenAPI enrichment, AnythingMCP yaml, and /skill.md. Repo doc: docs/MCP.md.

Native Streamable HTTP MCP on this origin is not required for v1 — AnythingMCP (or a future small MCP server) wraps the same curated surface.