<!-- carta:plugin-version --> <carta-plugin>carta-cap-table:6.93.3</carta-plugin>

<!-- Part of the official Carta AI Agent Plugin -->

Discover Commands

Use the command registry to find available commands when no specific skill covers the user's request. A prior discover call in this environment caches the full registry to disk — read that cache first and only hit the network on a miss.

Step 0 — Read the cached command registry (do this first)

The plugin's PostToolUse hook writes the full command registry to ${CLAUDE_PLUGIN_DATA}/cache/commands.json after any discover call. Read it before making any MCP call:

cat "${CLAUDE_PLUGIN_DATA}/cache/commands.json" 2>/dev/null || true

If the file exists and is valid, treat it as the command list and validate it before use:

• Freshness — the JSON has a cached_at ISO timestamp. If cached_at is more than 24 hours old, treat the cache as stale and fall through to Step 1 (this matches the 24h TTL the welcome/accounts caches use).
• Version — the JSON has a plugin_version. If it does not match the running plugin version (see the <carta-plugin version=… /> tag injected at session start), treat the cache as stale and fall through to Step 1.
• Shape — the command list lives under the commands key (an array). If the file is empty, unparseable, or commands is missing/empty, fall through to Step 1.

When the cache is valid and fresh, skip Steps 1–2's network call — pick the best-matching command directly from the cached commands array (same name / description / inputSchema fields as the live search_tools result) and go straight to Step 3. This removes a network round-trip on warm sessions.

Step 1 — Search for Relevant Commands (cache miss / stale only)

search_tools({"query": "<keyword from user's request>"})

Use a keyword that captures the user's intent (e.g. "valuation", "grant", "safe", "stakeholder").

Step 2 — Pick the Best Match

Review the returned tools. Each has:

• name: the tool name to pass to call_tool (e.g. cap_table__get__stakeholders)
• description: what it returns
• read_only: true if the tool only reads data

Only the top results also have inputSchema (the required and optional parameters). The others have required_params and optional_params (parameter names only), which are usually enough to call the tool. If you need a parameter's type or allowed values, call search_tools({"query": "<tool name>"}) with its exact name: that tool comes back first, with its inputSchema.

Step 3 — Execute

call_tool({"name": "<tool_name>", "arguments": { ...params }})

You still need corporation_id for most commands — get it from list_accounts if you don't have it.