Invoking Tools from the CLI

The markdocket call command lets you invoke any tool in the MarkDocket tool catalog directly from your terminal without opening a browser. You can script tool calls, pipe results into other commands, and iterate on queries in the same environment as your other development work.

Prerequisites

Before calling tools you must be authenticated. Run:

markdocket login

This opens a browser-based OAuth 2.1 flow and stores a session credential locally. Alternatively you can authenticate with a personal API key:

markdocket login --key <your-api-key>

See the authentication guide for full details on both modes.

Basic Usage

markdocket call <tool-name> [options]

Pass input arguments as a JSON string with --args (or -a):

markdocket call trademark_search --args '{"query": "ACME", "class": 25}'

Or read arguments from a file:

markdocket call trademark_search --args-file ./search-params.json

Pretty-print the response:

markdocket call trademark_search --args '{"query": "ACME"}' --pretty

Listing Available Tools

To see every tool you can call:

markdocket tools

This prints the name, a short description, and the category of each tool. To get the full JSON schema for a specific tool's inputs:

markdocket tools --tool trademark_search

The schema follows JSON Schema Draft 7 and describes every required and optional field, their types, and any enum constraints.

Tool Categories

Tools are organized into categories. Typical categories include:

• Trademark — search, status, and history for USPTO trademark records
• Patent — prior-art search, patentability review, application status
• Clearance — brand clearance and conflict detection
• Portfolio — portfolio and deadline management
• Filing — USPTO filing actions and status tracking
• Vault — document and artifact storage
• Automations — create and update automation workflows

Agent-Only Tools

A small number of tools — including web search and goods-classification helpers — are available only to the AI agent during interactive chat sessions and are not exposed through markdocket call. If a tool you expect to see is absent from markdocket tools, it is likely an agent-only tool.

Passing Arguments

Arguments are always a single JSON object whose keys match the tool's input schema. Validation happens before the call is sent, so schema errors are reported locally.

Inline JSON:

markdocket call patent_search --args '{"keywords": ["image recognition", "convolutional"], "filedAfter": "2020-01-01"}'

From a file:

# search-params.json
{
  "keywords": ["image recognition", "convolutional"],
  "filedAfter": "2020-01-01"
}

markdocket call patent_search --args-file ./search-params.json

Piping from another command:

echo '{"serialNumber": "87654321"}' | markdocket call trademark_status --args-stdin

Understanding the Response

A successful tool call returns a JSON envelope to stdout:

{
  "ok": true,
  "tool": "trademark_search",
  "result": {
    "hits": [
      {
        "serialNumber": "87654321",
        "mark": "ACME",
        "status": "REGISTERED",
        "class": [25],
        "filingDate": "2019-03-12"
      }
    ],
    "total": 1
  }
}

The exit code is 0 on success and non-zero on any error.

Polling Tools

Some tools start an asynchronous job and return a job ID rather than an immediate result. For these tools the CLI prints the job ID and instructions for checking status:

{
  "ok": true,
  "tool": "prior_art_scan_start",
  "result": {
    "jobId": "job_abc123",
    "status": "queued"
  }
}

Use the corresponding status or result tool to retrieve the outcome:

markdocket call prior_art_scan_status --args '{"jobId": "job_abc123"}'

Some higher-level CLI commands (such as markdocket patent review) wrap this polling loop automatically.

Error Responses

When a tool call fails, the envelope uses ok: false and includes an error object:

{
  "ok": false,
  "tool": "trademark_search",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "'query' is required"
  }
}

Common error codes:

Billing Errors

If your account does not have sufficient balance or credit to complete a tool call, the CLI returns a billing error with a specific required action:

{
  "ok": false,
  "tool": "prior_art_scan_start",
  "error": {
    "code": "BILLING_BLOCKED",
    "reason": "insufficient_balance",
    "requiredAction": "add_funds",
    "message": "Your account balance is too low to start this scan."
  }
}

The requiredAction field tells you exactly what to do: add_funds, upgrade_plan, or enable_payg are the most common values. Visit your billing settings in the web app to take the indicated action, then retry.

Idempotent Calls

For tools that create or modify resources, the CLI automatically attaches an idempotency key derived from your arguments and session. If you retry the exact same call (same tool, same arguments, same session), the platform returns the result of the first attempt rather than performing the action again.

To force a fresh execution with a new idempotency key:

markdocket call <tool-name> --args '{...}' --no-idempotency

Scripting and CI Usage

Exit Codes

Machine-Readable Output

By default the CLI writes compact JSON. Pass --pretty for indented output when working interactively. In scripts, parse the compact output with any JSON tool:

STATUS=$(markdocket call trademark_status --args '{"serialNumber":"87654321"}' | jq -r '.result.status')
echo "Status: $STATUS"

Non-Interactive Authentication in CI

For CI environments, set a personal API key and pass it directly:

markdocket call trademark_search --args '{"query": "ACME"}' --key $MARKDOCKET_API_KEY

Or configure the key once in CI secrets and rely on markdocket login --key run during setup.

MCP Tool Invocation

If you are building an AI agent or tool-calling pipeline that uses the Model Context Protocol, the same tools are available via the MarkDocket stdio MCP server:

markdocket mcp

This starts a long-running stdio MCP server that exposes every tool in the catalog with MCP-standard annotations (readOnlyHint, destructiveHint, idempotentHint) derived automatically from each tool's definition. See the MCP integration guide for configuration details.

Next Steps

• Browse the full tool reference — run markdocket tools for the current list, or markdocket tools --tool <name> for a tool's schema
• Automate multi-step research — use markdocket patent review or markdocket automations for orchestrated workflows
• Integrate via MCP — connect any MCP-compatible AI agent to the same tool surface with markdocket mcp
• API access — the same tools are available over REST at /v1/tools for server-side integrations using a personal API key