Tool Discovery and Testing

Workestra exposes a broad, versioned tool catalog. A specific API key sees only the subset allowed by its effective permissions. Always retrieve the live catalog instead of relying on a cached tool count.

The hosted discovery API is the source of truth for:

• Tool names and descriptions
• Read/write classification
• Feature group
• Required permission and legacy permission aliases
• Whether the tested key is allowed to call the tool
• JSON input schema

Verify the session

curl "https://platform.workestra.app/api/mcp/session" \
  -H "Authorization: Bearer $WORKESTRA_API_KEY"

Response:

{
  "ok": true,
  "apiKeyName": "Codex MCP",
  "workspaceId": "workspace-uuid",
  "actorUserId": "user-uuid",
  "permissions": {
    "granted": ["read_contacts"],
    "allKnown": ["read_contacts", "create_contacts"]
  },
  "capabilities": {
    "totalTools": 120,
    "allowedToolCount": 42,
    "deniedToolCount": 78,
    "allowedToolNames": ["...permission-dependent tool names..."],
    "allowedFeatures": ["...permission-dependent feature groups..."]
  }
}

The total reflects the deployed registry. Allowed/denied counts and names are illustrative and depend on the tested key.

List tools

GET /api/mcp/tools/list
Authorization: Bearer wks_...

Query parameters:

Complete audit request:

curl "https://platform.workestra.app/api/mcp/tools/list?includeDenied=true&includeSchemas=true" \
  -H "Authorization: Bearer $WORKESTRA_API_KEY"

Read-only CRM subset:

curl "https://platform.workestra.app/api/mcp/tools/list?readOnly=true&features=contacts,deals,companies" \
  -H "Authorization: Bearer $WORKESTRA_API_KEY"

POST /api/mcp/tools/list accepts the same options as JSON:

{
  "includeDenied": true,
  "includeSchemas": true,
  "readOnly": false,
  "features": ["contacts", "deals"]
}

Call a tool directly

POST /api/mcp/tools/call
Authorization: Bearer wks_...
Content-Type: application/json

{
  "name": "search_contacts",
  "arguments": {
    "query": "Acme"
  }
}

Use the input schema returned by /tools/list; do not guess argument names.

Success:

{
  "data": {},
  "entities": [
    {
      "entity_type": "contact",
      "entity_id": "contact-uuid"
    }
  ]
}

Feature groups

Feature groups span CRM, projects, support, finance, people, scheduling, operations, reporting, and automation. Use the allowedFeatures and allowedToolNames returned for the current credential as the authoritative inventory. This avoids stale integrations as tools are added or permissions change.

Rate limits

The session, list, and call endpoints currently enforce:

• 600 requests/minute per source IP
• 600 requests/minute per workspace

On 429, honor Retry-After and the X-RateLimit-* headers.

Errors

Agent-trial differences

Agent-trial keys:

• Use a guarded tool allowlist.
• Exclude high-risk external side effects and administrative capabilities.
• Expire after seven days under the current contract.
• Are capped at 250 tool calls under the current contract.

Always trust /api/mcp/session and /api/mcp/tools/list for the actual tested credential.

For unresolved permission or schema discrepancies, follow API and MCP Troubleshooting or email support@workestra.app with the tool name, adapter version, workspace ID, and sanitized response. Never send the key.

Testing checklist

1. Pin or record the workestra-mcp npm version.
2. Confirm /api/mcp/session succeeds.
3. Store the returned allowedToolNames.
4. Retrieve schemas with /api/mcp/tools/list.
5. Call a read tool with known-safe arguments.
6. Verify a denied or unknown tool fails as expected.
7. Test one disposable write only after confirming the permission and cleanup path.
8. Revoke the temporary key after testing.