MCP Tool Catalog Design: Make Large Server Catalogs Easier to Use

A large MCP catalog is an interface, not an inventory dump. Every extra tool competes for attention, context, and selection. A catalog that is technically complete can still be hard for an agent to use when names overlap, descriptions omit constraints, or the list changes between discovery and execution.

Start with the tasks users need to complete

Group tools by domain and workflow, then decide whether every action deserves a separate tool. A tool that accepts ten unrelated modes may reduce the number of names but increase schema ambiguity. Several narrow tools may be easier to authorize and explain, while too many near-duplicates can make selection worse. The right boundary is the one that makes intent, permission, and failure behavior clear.

• Give every tool one primary job and one recognizable result shape.
• Put authorization and side-effect information in the description and annotations where appropriate.
• Avoid exposing internal implementation details that do not help a client choose the tool.
• Keep administrative or destructive tools separate from routine read tools in naming and permission policy.

Pagination is part of the catalog contract

MCP list operations can return a nextCursor when more results are available. A cursor is opaque. The client should pass it back unchanged and continue until the server omits it. The server owns page size and cursor semantics. Do not make clients parse an offset, assume a stable page length, or silently discard a partial catalog.

let cursor: string | undefined;
do {
  const page = await client.listTools(cursor);
  consume(page.tools);
  cursor = page.nextCursor;
} while (cursor);

Production clients should bound the number of pages and detect a repeated cursor. Servers should make a reasonable effort to keep a page walk coherent, but a rapidly changing catalog can still create additions, removals, or duplicates between pages. Document the behavior and include a catalog or deployment identifier in debugging output.

Cache freshness is not authorization

A client may cache a tools/list response to avoid repeated discovery. Freshness and visibility are separate decisions. A catalog that varies by user, tenant, role, or token must not be shared merely because it has a TTL. If the server advertises list-change notifications, clients can invalidate or refresh their view before the nominal TTL expires.

Descriptions and schemas should agree

The description is the selection guidance and the input schema is the validation contract. If the description says a filter is optional but the schema requires it, agents will retry or abandon the tool. If a field accepts an enum but the description uses different labels, selection will be unreliable. Review the rendered catalog, not only the source code.

Discovery is not execution

A tool can be listed, selected, and then rejected by authorization or input validation. It can also be called successfully but fail inside its result with isError true. Measure these stages separately: catalog exposure, selection evidence when available, call attempt, validation outcome, execution outcome, and workflow result.

TrackMCP observes what reaches the server boundary. It can help you see which tools are called, which clients connect, where calls fail, how latency changes, and whether explicit workflow outcomes improve. It cannot see tools that a host considered but never sent to the server, and it cannot infer a complete model decision from the absence of a call.

A release checklist for catalog changes

• Check names for uniqueness, allowed characters, and stable meaning.
• Validate every input and output schema, including empty-input tools.
• Test first page, middle page, final page, repeated cursor, and changing-catalog behavior.
• Test permissions against a fresh catalog and a stale cached catalog.
• Run representative workflows with at least two clients and compare selection, errors, retries, and completion.