---
title: "Same catalog search as the MCP `search` tool, including exact `entity` refs."
method: POST
path: "/v1/search/tool"
tags: ["search"]
---

# Same catalog search as the MCP \`search\` tool, including exact \`entity\` refs.

`POST /v1/search/tool`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/search/tool`
- Auth: HTTP bearer

Same catalog search as the MCP `search` tool, including exact `entity` refs. Requires `search:read`. The result envelope matches the tool (`content`, `structuredContent`, `isError`). `GET /v1/search` remains the capability.

Org permission: `search:read`.

## Request body

- object
  - `query` string: Natural language description, or a scoped `@owner/leaf` name, current-origin account package URL, owner-matching hosted package URL, or an exact saved-package UUID (`package_id`) when the name is not known.
  - `entity` union: Optional exact entity reference "{type}:{id}" (capability, guide, integration, mcp-server, package, or secret), or an array of refs to batch related detail lookups. Guide refs accept "#{heading}" or a line anchor "#L165" / "#L165-L180". Package refs accept "#{subpath}" to open one export contract (leading "./" is optional), or "#{path}" / "#{path}#L165" / "#{path}#heading" to open one file. A fragment that matches an export subpath still opens that export. Use "mcp-server:{name}" to list tools on a connected MCP server.
    - string
    - string[]
  - `domain` string: Optional capability domain id (for example "email" or "mcp:linear"). With "query", ranks only that domain's capabilities; without "query", lists the domain's capabilities.
  - `limit` integer: Number of ranked results to return. Defaults to 15.
  - `maxResponseSize` integer: Response size budget before trimming low-ranked results. Defaults to 4000.
  - `conversationId` string: Optional short conversation identifier. Ties related calls together. If you already have a `conversationId` from an earlier response in the same conversation, pass it back unchanged. Otherwise omit this field to receive a server-generated ID, then reuse the returned `conversationId` on subsequent calls - this enables optimizations like reduced response size. Do not invent your own `conversationId`.
  - `memoryContext` object: Optional short, structured task context for memory retrieval. Keep it brief and factual rather than hidden reasoning. If durable memory may need to be written or deleted, agents should later run `metaMemoryVerify` before mutating memory.
    - `task` string: Optional task or goal summary for future memory retrieval.
    - `query` string: Optional task or goal summary for future memory retrieval.
    - `entities` string[]: Optional short phrases that identify important entities, constraints, or references for future memory retrieval.
    - `constraints` string[]: Optional short phrases that identify important entities, constraints, or references for future memory retrieval.
  - `includeHiddenPackages` boolean: Include hidden packages in search results (hidden packages are excluded by default).

## Response `200`

Success.

- object
  - `content` unknown[], required
    - unknown
  - `structuredContent` object, required
  - `isError` boolean, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)