{
  "access": "public",
  "type": "reference",
  "format": "markdown",
  "title": "Discovery Tools Reference",
  "chunked": true,
  "url": "https://library.datagrout.ai/discovery-tools",
  "summary": "Discover tools, plan workflows, explore capabilities, and execute tool calls across your integration mesh.",
  "content_markdown": "# Discovery Tools\n\nDiscover tools, plan workflows, explore capabilities, and execute tool calls across your integration mesh.\n\nDiscovery tools let your agents find tools by describing what they need in natural language, build verified multi-step plans, navigate available capabilities interactively, and get a bird's-eye summary of the platform. All five tools are available on every server at `data-grout@1/discovery.*@1`.\n\n---\n\n## `discovery.discover@1`\n\nSearch for tools semantically. Describe what you want to accomplish, and Discover returns ranked matches from your integration mesh.\n\nYou can also pass an array of queries to search in batch. Each query runs independently and returns its own result set.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `goal` | string | yes | -- | Natural language description of what you want to accomplish |\n| `limit` | integer | no | 10 | Maximum number of results to return |\n| `min_score` | number | no | 0 | Minimum relevance score (0--1). Results below this threshold are excluded |\n| `coverage_gaps` | boolean | no | false | Include analysis of what tools are missing to fully achieve the goal |\n| `integrations` | array | no | all | Filter results to specific integrations (e.g. `[\"salesforce\", \"quickbooks\"]`) |\n| `servers` | array | no | current | Search across specific servers by UUID. Defaults to the current server only |\n| `demux` | boolean | no | false | Include tools from demuxable servers in search results |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/discovery.discover@1\",\n  \"arguments\": {\n    \"goal\": \"find customers with unpaid invoices\",\n    \"limit\": 5,\n    \"integrations\": [\"quickbooks\"]\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"query_used\": \"find customers with unpaid invoices\",\n  \"results\": [\n    {\n      \"tool\": {\n        \"name\": \"quickbooks@1/list_invoices@1\",\n        \"description\": \"List invoices filtered by status, customer, or date range\",\n        \"inputSchema\": { \"...\" : \"...\" }\n      },\n      \"score\": 0.91\n    },\n    {\n      \"tool\": {\n        \"name\": \"quickbooks@1/get_customer@1\",\n        \"description\": \"Get a customer record by ID\",\n        \"inputSchema\": { \"...\" : \"...\" }\n      },\n      \"score\": 0.74\n    }\n  ]\n}\n```\n\n### Batch search\n\nPass an array to search multiple goals in one call:\n\n```json\n[\n  { \"goal\": \"get leads from CRM\", \"limit\": 3 },\n  { \"goal\": \"create an invoice\", \"limit\": 3 }\n]\n```\n\nReturns an array of result sets, one per query.\n\n---\n\n## `discovery.plan@1`\n\nBuild a verified multi-step workflow for a goal. The planner searches your tool graph, inserts type adapters where needed, and validates the result before returning it. Plans come with a Cognitive Trust Certificate confirming they are cycle-free, type-safe, and policy-compliant.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `goal` | string | yes | -- | Natural language description of the workflow goal |\n| `query` | string | no | -- | Alternative to `goal` for shorter search-style queries |\n| `k` | integer | no | 5 | Number of candidate plans to evaluate |\n| `policy` | object | no | server default | Policy overrides: `max_cost`, `read_only`, `allowed_integrations` |\n| `have` | object | no | -- | Contextual hint telling the planner what data exists. Describes where data lives (e.g. `{\"services\": \"asserted in logic cell\"}`), not the data itself. Not piped to tools at runtime — use `inputs` on `discovery.perform` for that |\n| `return_call_handles` | boolean | no | true | Include callable handles for each step so you can execute them directly |\n| `expose_virtual_skills` | boolean | no | true | Surface saved skills that match the goal alongside tool-based plans |\n\n### `have` vs `inputs`\n\n`have` and `inputs` serve different purposes:\n\n- **`have`** (on `plan`) is a **planning-time hint**. It tells the planner what context already exists so it can select the right first step. Example: `\"have\": {\"services\": \"asserted in logic cell\"}` tells the planner to start with `logic.tabulate` instead of fetching data from an integration.\n\n- **`inputs`** (on `perform` with `skill_handle`) is **runtime data** piped to the first step of the virtual skill as its `payload`. Use this when the virtual skill's first step needs data you have in hand.\n\nPlans whose first step pulls from an existing data source (logic cell, integration, cache) work without `inputs`. Plans whose first step operates on data you provide (e.g. `math.outliers` on a numeric array) need `inputs` at execution time.\n\n`inputs` accepts several formats — the system auto-unwraps them:\n\n- `{\"payload\": [1, 2, 3]}` — unwraps to `[1, 2, 3]`\n- `{\"input\": [1, 2, 3]}` — unwraps to `[1, 2, 3]`\n- `{\"values\": [1, 2, 3]}` — unwraps to `[1, 2, 3]`\n- `{\"data\": [1, 2, 3]}` — unwraps to `[1, 2, 3]`\n- `[1, 2, 3]` — passed through directly\n\nRaw numbers are accepted by math tools even when the plan specifies a `field` parameter — the field is ignored when the data is already numeric.\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/discovery.plan@1\",\n  \"arguments\": {\n    \"goal\": \"Create QuickBooks invoices from qualified Salesforce leads\",\n    \"policy\": { \"max_cost\": 100 }\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"plan_id\": \"plan_abc123\",\n  \"steps\": [\n    {\n      \"step\": 1,\n      \"tool\": \"salesforce@1/get_leads@1\",\n      \"args\": { \"status\": \"Qualified\" },\n      \"output_type\": \"crm.lead@1\"\n    },\n    {\n      \"step\": 2,\n      \"tool\": \"data-grout@1/prism.focus@1\",\n      \"args\": { \"source_type\": \"crm.lead@1\", \"target_type\": \"billing.customer@1\" },\n      \"output_type\": \"billing.customer@1\"\n    },\n    {\n      \"step\": 3,\n      \"tool\": \"quickbooks@1/create_invoice@1\",\n      \"args\": { \"customer\": \"$step2.result\" },\n      \"output_type\": \"billing.invoice@1\"\n    }\n  ],\n  \"estimated_cost\": 45,\n  \"safe\": true,\n  \"ctc_id\": \"ctc_xyz789\"\n}\n```\n\nUse the returned `plan_id` to execute the plan, or inspect individual steps using the call handles.\n\n---\n\n## `discovery.guide@1`\n\nNavigate your integration mesh interactively. Guide presents options at each step, you choose, and the system narrows down until it reaches a concrete tool or workflow. Guide maintains session state across calls, so you can go back and explore different branches.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` / `goal` | string | yes (first call) | -- | What you want to accomplish. Required on the first call; optional on subsequent calls within the same session |\n| `session_id` | string | no | -- | Session identifier returned from a previous Guide call. Pass this to continue the conversation |\n| `choice` | string | no | -- | Your selection from the options presented in the previous response |\n| `back` | boolean | no | false | Go back one step in the current session |\n| `save_as_skill` | boolean | no | false | Save the completed workflow as a reusable skill |\n\n### Example\n\nFirst call:\n\n```json\n{\n  \"name\": \"data-grout@1/discovery.guide@1\",\n  \"arguments\": {\n    \"goal\": \"sync data between my CRM and billing system\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"session_id\": \"guide_abc123\",\n  \"message\": \"What kind of data do you want to sync?\",\n  \"options\": [\n    { \"label\": \"Customers / Contacts\", \"value\": \"customers\" },\n    { \"label\": \"Invoices / Bills\", \"value\": \"invoices\" },\n    { \"label\": \"Products / Items\", \"value\": \"products\" }\n  ]\n}\n```\n\nFollow-up call:\n\n```json\n{\n  \"name\": \"data-grout@1/discovery.guide@1\",\n  \"arguments\": {\n    \"session_id\": \"guide_abc123\",\n    \"choice\": \"customers\"\n  }\n}\n```\n\nThe system continues narrowing until it reaches a concrete plan or tool. At that point you can execute directly or save the result as a skill.\n\n---\n\n## `discovery.perform@1`\n\nExecute a tool by name. Perform is the execution layer: you specify a tool and its arguments, and it runs. You can also pass an array to execute multiple tools in parallel, or enable demux to broadcast a call across compatible servers.\n\nPerform also supports inline data transformation (`refract`) and chart generation (`chart`) on the result.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `tool` | string | yes | -- | Full tool name (e.g. `salesforce@1/get_leads@1`) |\n| `args` | object | yes | -- | Arguments to pass to the tool |\n| `skill_handle` | string | no | -- | Execute a saved skill instead of a raw tool |\n| `inputs` | object/array | no | -- | Runtime data piped to the first step's `payload`. Use when the skill's first step needs data you have in hand (e.g. a numeric array for `math.outliers`). Not needed when the first step pulls from an existing source like the logic cell or an integration |\n| `save_as_skill` | boolean | no | false | Save this execution as a reusable skill |\n| `demux` | boolean | no | false | Broadcast this call across all servers with a compatible tool |\n| `demux_mode` | string | no | `\"strict\"` | `\"strict\"` requires exact tool name match; `\"fuzzy\"` matches semantically compatible tools |\n| `refract` | string | no | -- | Natural language transformation to apply to the result |\n| `chart` | string | no | -- | Generate a chart from the result (e.g. `\"bar chart of revenue by month\"`) |\n\n### Example: single call\n\n```json\n{\n  \"name\": \"data-grout@1/discovery.perform@1\",\n  \"arguments\": {\n    \"tool\": \"salesforce@1/get_leads@1\",\n    \"args\": { \"status\": \"Qualified\", \"limit\": 10 }\n  }\n}\n```\n\n### Example: batch execution\n\n```json\n[\n  { \"tool\": \"salesforce@1/get_leads@1\", \"args\": { \"limit\": 10 } },\n  { \"tool\": \"quickbooks@1/list_invoices@1\", \"args\": { \"status\": \"unpaid\" } }\n]\n```\n\n### Example: demux write\n\n```json\n{\n  \"name\": \"data-grout@1/discovery.perform@1\",\n  \"arguments\": {\n    \"tool\": \"quickbooks@1/create_invoice@1\",\n    \"args\": { \"customer_id\": \"cust_123\", \"amount\": 500 },\n    \"demux\": true,\n    \"demux_mode\": \"strict\"\n  }\n}\n```\n\nReturns results from every server that has a matching tool:\n\n```json\n{\n  \"mode\": \"strict\",\n  \"results\": [\n    { \"server_name\": \"Production\", \"success\": true, \"result\": { \"...\" : \"...\" } },\n    { \"server_name\": \"Staging\", \"success\": true, \"result\": { \"...\" : \"...\" } }\n  ],\n  \"total_targets\": 2,\n  \"successful\": 2\n}\n```\n\n---\n\n## `discovery.summary@1`\n\nGet a compact overview of all available tool suites and capabilities without fetching full schemas. Use this to understand what the platform can do before issuing specific discovery queries.\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `scope` | string | no | `\"platform\"` | What to show: `\"platform\"` = full DataGrout capabilities, `\"server\"` = only tools on your server, `\"all\"` = both with availability flags |\n| `include_tools` | boolean | no | `false` | Include 1-line per-tool summaries within each suite |\n| `focus` | string | no | -- | Return detailed info for just one suite (e.g. `\"logic\"`, `\"frame\"`, `\"discovery\"`) |\n\n### Example\n\n```json\n{\n  \"name\": \"data-grout@1/discovery.summary@1\",\n  \"arguments\": {\n    \"include_tools\": true,\n    \"focus\": \"logic\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"suites\": [\n    {\n      \"name\": \"logic\",\n      \"description\": \"Persistent symbolic memory. Store, query, and reason over facts using a Prolog-backed knowledge base.\",\n      \"tool_count\": 8,\n      \"capabilities\": [\"fact storage\", \"NL queries\", \"constraint rules\", \"goal-driven hydration\", \"transitive reasoning\", \"export/import\"],\n      \"tools\": [\n        {\"name\": \"remember\", \"one_liner\": \"Store facts (natural language or structured)\"},\n        {\"name\": \"query\", \"one_liner\": \"Query facts by pattern or natural language\"},\n        {\"name\": \"forget\", \"one_liner\": \"Remove facts from memory\"},\n        {\"name\": \"constrain\", \"one_liner\": \"Add constraint rules\"},\n        {\"name\": \"reflect\", \"one_liner\": \"Introspect on the fact space\"},\n        {\"name\": \"hydrate\", \"one_liner\": \"Goal-driven context hydration\"},\n        {\"name\": \"export\", \"one_liner\": \"Export facts as JSON\"},\n        {\"name\": \"import\", \"one_liner\": \"Import facts from JSON\"}\n      ]\n    }\n  ],\n  \"total_tools\": 8,\n  \"total_suites\": 1,\n  \"message\": \"1 tool suites with 8 tools. Showing details for 'logic' suite.\"\n}\n```\n\n### Cost\n\n0 credits — pure metadata lookup.\n\n### Tips\n\n- Use `scope: \"all\"` to see which suites are available on your server vs. the full platform\n- Use `focus` to drill into a specific suite before calling `discovery.discover` with a targeted goal\n- Use `include_tools: true` when you need tool names but not full schemas\n\n---\n\n## When to use which tool\n\n| Situation | Tool |\n|-----------|------|\n| You want a high-level map of platform capabilities | `summary` |\n| You know what you want but not which tool does it | `discover` |\n| You need a multi-step workflow with guarantees | `plan` |\n| You want to explore what's possible interactively | `guide` |\n| You know the exact tool and want to run it | `perform` |\n"
}