Agent Tool System

The MarkDocket agent uses a structured tool registry to perform IP research, trademark searches, patent analysis, and related operations during a chat session. This page explains how the registry is organized, which tools are available to the agent versus the public CLI and MCP surfaces, and how the agent issues requests back to the platform on your behalf.

How the tool registry works

MarkDocket maintains two related but distinct tool catalogs:

• The public catalog — the authoritative list of tools exposed through the CLI (markdocket call <name>), the stdio MCP server, the /v1/tools REST gateway, and the hosted /mcp streaming endpoint. This catalog lives in the @markdocket/cli package and is the single source of truth for all external tool surfaces. Any tool added to this catalog automatically appears in every external surface without additional wiring.

• The agent registry — a superset of the public catalog. The agent has access to all public tools plus a set of agent-only tools that are unavailable on external surfaces. The public catalog is derived from the agent registry by applying an exclusion list at build time.

Because the CLI, hosted MCP endpoint, and /v1/tools gateway all derive from the same registry, tool names, input schemas, descriptions, and behavioral hints are always consistent across every surface.

MCP tool annotations

The hosted MCP server and stdio MCP server both compute MCP behavioral annotations — readOnlyHint, idempotentHint, and destructiveHint — automatically from metadata already present on each tool definition (its HTTP method and read-only flag), plus a name-pattern check for operations like delete, remove, or cancel. There is no separate annotation registry to maintain.

Agent-only tools

The following tools are available only inside agent chat sessions. They are explicitly excluded from the CLI, stdio MCP server, /v1/tools gateway, and hosted /mcp endpoint via the EXTERNAL_TOOL_EXCLUSIONS list:

These tools depend on the agent worker's own AI Gateway key or a durable chat session context, which is not available to API-key or OAuth-token callers on external surfaces.

How the agent calls back to the API

The agent worker is fully trust-isolated: it holds no direct credentials for USPTO data, brand intelligence, or any other data worker. Instead, every tool call the agent makes routes back through the MarkDocket API using a delegated user JWT (X-Delegated-Token). The API then re-dispatches the request to the appropriate internal worker.

This design has several practical consequences:

• Your permissions apply. The agent can only perform actions that your account is authorized for. The delegated JWT carries your identity, so no tool call can exceed your access level.
• All agent actions are audited. Because every tool call passes through the API, it is recorded in the platform's audit log (agent session, turn, message, and attachment records).
• Compromising the agent worker does not expose internal credentials. The agent worker has no direct access to database credentials, USPTO API keys, Stripe keys, or any sibling worker secrets.

Agent turn lifecycle

Before the agent can begin a turn, the platform runs a pre-authorization step:

1. A billing reservation is created atomically as the turn transitions from authorizing to authorized.
2. File uploads (if any) are validated against the active reservation and bound to the turn.
3. The agent begins the LLM tool-calling loop, streaming results back as server-sent events (SSE).
4. The turn concludes in one of: completed, denied, failed, expired, or cancelled.

If the turn is abandoned or expires, a background sweep releases the billing reservation and removes any orphaned uploaded files.

Idempotent file uploads

File uploads within an agent turn are idempotent. If the same file is submitted more than once under the same idempotency key, the platform recognizes and deduplicates the upload without an extra database lookup. This means retrying an upload after a network interruption is safe.

Billing blocks in tool results

If a tool call requires a plan upgrade or additional usage authorization, the agent turn emits a billing_required event over its SSE stream. This event carries a structured BillingBlockEnvelope that the client uses to present the appropriate billing action.

Billing blocks are intercepted at the streaming transport layer — individual tool calls do not need to handle them. If a billing block appears mid-stream, the platform pauses the turn and presents you with the relevant upgrade or authorization step before the turn can continue.

The same billing block type flows consistently across all surfaces:

• Agent chat: billing_required SSE event
• Automation runs: a suspending signal that pauses the run without marking it failed
• CLI: a human-readable error with an action hint
• MCP server: a structured error with isError: true and structuredContent

Public tool surfaces

All tools in the public catalog are accessible through three equivalent surfaces. The tool names, schemas, and behavior are identical on each.

CLI

Run any cataloged tool directly:

markdocket call <tool-name> [options]

Authenticate with markdocket login (browser OAuth) before calling tools. Password-authenticated sessions also support direct tool calls.

Stdio MCP server

The @markdocket/cli package ships a stdio MCP server that exposes the full public catalog to any MCP-compatible AI client:

markdocket mcp

Configure your MCP client to launch this command as a local stdio transport.

Hosted MCP endpoint and /v1/tools gateway

MarkDocket also provides a hosted streaming MCP endpoint and a REST tool gateway at /v1/tools. Both require authentication:

• Hosted MCP (/mcp): Uses OAuth 2.1 access tokens. Supports dynamic client registration — the CLI's markdocket login flow registers a session-specific client automatically.
• REST gateway (/v1/tools): Uses personal API keys. Suitable for server-to-server integrations.

Tool result compaction for MCP

Some tools return large payloads. When serving tools over MCP, the platform applies domain-aware compaction before enforcing the response size limit:

• Polling tools (such as scan-status tools) strip large intermediate fields like raw findings and report markdown, since those are available on the final result.
• Final result tools retain findings in full.
• Full report tools pass through unmodified.

If compaction still leaves the result over the size limit, the first 150,000 characters are returned as a preview with a truncated: true flag — not an error — so the calling client always receives a usable response.

Summary