---
title: MCP tool design
description: "How BennyBooks shapes MCP tools for clean, token-efficient agent use."
canonical: https://bennybooks.com/developers/guides/mcp-design
markdown: https://bennybooks.com/developers/guides/mcp-design.md
---
# MCP tool design

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

> **Documentation index.** Fetch [https://bennybooks.com/developers/llms.txt](https://bennybooks.com/developers/llms.txt) before browsing further. Prefer markdown (this file or `Accept: text/markdown`). Site-wide map: [https://bennybooks.com/llms.txt](https://bennybooks.com/llms.txt).

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 — native /api/mcp exposes this set; disable redundant ops in OpenAPI bridges
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 |
| import_revolut_csv | propose-write | Import Revolut CSV |
| 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 (https://bennybooks.com/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 the native /api/mcp server, OpenAPI enrichment, AnythingMCP yaml, and https://bennybooks.com/skill.md. Repo doc: docs/MCP.md.

Prefer native Streamable HTTP at /api/mcp (see Connect Streamable HTTP MCP). AnythingMCP remains a supported OpenAPI bridge.

---

## Machine-readable

- HTML: https://bennybooks.com/developers/guides/mcp-design
- Markdown: https://bennybooks.com/developers/guides/mcp-design.md
- Docs index: https://bennybooks.com/developers/llms.txt
- OpenAPI: https://bennybooks.com/openapi.json
- Skill: https://bennybooks.com/skill.md
- Auth: https://bennybooks.com/auth.md

```json
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "MCP tool design",
  "description": "How BennyBooks shapes MCP tools for clean, token-efficient agent use.",
  "url": "https://bennybooks.com/developers/guides/mcp-design",
  "inLanguage": "en",
  "encodingFormat": [
    "text/html",
    "text/markdown"
  ],
  "isAccessibleForFree": true,
  "publisher": {
    "@type": "Organization",
    "name": "BennyBooks",
    "url": "https://bennybooks.com",
    "logo": {
      "@type": "ImageObject",
      "url": "https://bennybooks.com/apple-icon.png"
    }
  },
  "mainEntityOfPage": "https://bennybooks.com/developers/guides/mcp-design",
  "image": "https://bennybooks.com/opengraph-image",
  "workExample": {
    "@type": "CreativeWork",
    "url": "https://bennybooks.com/developers/guides/mcp-design.md",
    "encodingFormat": "text/markdown",
    "name": "MCP tool design (Markdown)"
  },
  "about": {
    "@type": "WebAPI",
    "name": "BennyBooks Agent API",
    "url": "https://bennybooks.com/api/v1",
    "documentation": "https://bennybooks.com/developers"
  }
}
```
