Discovery Tools

Discover tools, plan workflows, explore capabilities, and execute tool calls across your integration mesh.

Discovery 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.

discovery.discover@1

Search for tools semantically. Describe what you want to accomplish, and Discover returns ranked matches from your integration mesh.

You can also pass an array of queries to search in batch. Each query runs independently and returns its own result set.

Parameters

Example

{
  "name": "data-grout@1/discovery.discover@1",
  "arguments": {
    "goal": "find customers with unpaid invoices",
    "limit": 5,
    "integrations": ["quickbooks"]
  }
}

Response:

{
  "query_used": "find customers with unpaid invoices",
  "results": [
    {
      "tool": {
        "name": "quickbooks@1/list_invoices@1",
        "description": "List invoices filtered by status, customer, or date range",
        "inputSchema": { "..." : "..." }
      },
      "score": 0.91
    },
    {
      "tool": {
        "name": "quickbooks@1/get_customer@1",
        "description": "Get a customer record by ID",
        "inputSchema": { "..." : "..." }
      },
      "score": 0.74
    }
  ]
}

Batch search

Pass an array to search multiple goals in one call:

[
  { "goal": "get leads from CRM", "limit": 3 },
  { "goal": "create an invoice", "limit": 3 }
]

Returns an array of result sets, one per query.

discovery.plan@1

Build 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.

Parameters

have vs inputs

have and inputs serve different purposes:

• 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.

• 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.

Plans 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.

inputs accepts several formats — the system auto-unwraps them:

• {"payload": [1, 2, 3]} — unwraps to [1, 2, 3]
• {"input": [1, 2, 3]} — unwraps to [1, 2, 3]
• {"values": [1, 2, 3]} — unwraps to [1, 2, 3]
• {"data": [1, 2, 3]} — unwraps to [1, 2, 3]
• [1, 2, 3] — passed through directly

Raw numbers are accepted by math tools even when the plan specifies a field parameter — the field is ignored when the data is already numeric.

Example

{
  "name": "data-grout@1/discovery.plan@1",
  "arguments": {
    "goal": "Create QuickBooks invoices from qualified Salesforce leads",
    "policy": { "max_cost": 100 }
  }
}

Response:

{
  "plan_id": "plan_abc123",
  "steps": [
    {
      "step": 1,
      "tool": "salesforce@1/get_leads@1",
      "args": { "status": "Qualified" },
      "output_type": "crm.lead@1"
    },
    {
      "step": 2,
      "tool": "data-grout@1/prism.focus@1",
      "args": { "source_type": "crm.lead@1", "target_type": "billing.customer@1" },
      "output_type": "billing.customer@1"
    },
    {
      "step": 3,
      "tool": "quickbooks@1/create_invoice@1",
      "args": { "customer": "$step2.result" },
      "output_type": "billing.invoice@1"
    }
  ],
  "estimated_cost": 45,
  "safe": true,
  "ctc_id": "ctc_xyz789"
}

Use the returned plan_id to execute the plan, or inspect individual steps using the call handles.

discovery.guide@1

Navigate 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.

Parameters

Example

First call:

{
  "name": "data-grout@1/discovery.guide@1",
  "arguments": {
    "goal": "sync data between my CRM and billing system"
  }
}

Response:

{
  "session_id": "guide_abc123",
  "message": "What kind of data do you want to sync?",
  "options": [
    { "label": "Customers / Contacts", "value": "customers" },
    { "label": "Invoices / Bills", "value": "invoices" },
    { "label": "Products / Items", "value": "products" }
  ]
}

Follow-up call:

{
  "name": "data-grout@1/discovery.guide@1",
  "arguments": {
    "session_id": "guide_abc123",
    "choice": "customers"
  }
}

The 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.

discovery.perform@1

Execute 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.

Perform also supports inline data transformation (refract) and chart generation (chart) on the result.

Parameters

Example: single call

{
  "name": "data-grout@1/discovery.perform@1",
  "arguments": {
    "tool": "salesforce@1/get_leads@1",
    "args": { "status": "Qualified", "limit": 10 }
  }
}

Example: batch execution

[
  { "tool": "salesforce@1/get_leads@1", "args": { "limit": 10 } },
  { "tool": "quickbooks@1/list_invoices@1", "args": { "status": "unpaid" } }
]

Example: demux write

{
  "name": "data-grout@1/discovery.perform@1",
  "arguments": {
    "tool": "quickbooks@1/create_invoice@1",
    "args": { "customer_id": "cust_123", "amount": 500 },
    "demux": true,
    "demux_mode": "strict"
  }
}

Returns results from every server that has a matching tool:

{
  "mode": "strict",
  "results": [
    { "server_name": "Production", "success": true, "result": { "..." : "..." } },
    { "server_name": "Staging", "success": true, "result": { "..." : "..." } }
  ],
  "total_targets": 2,
  "successful": 2
}

discovery.summary@1

Get 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.

Parameters

Example

{
  "name": "data-grout@1/discovery.summary@1",
  "arguments": {
    "include_tools": true,
    "focus": "logic"
  }
}

Response:

{
  "suites": [
    {
      "name": "logic",
      "description": "Persistent symbolic memory. Store, query, and reason over facts using a Prolog-backed knowledge base.",
      "tool_count": 8,
      "capabilities": ["fact storage", "NL queries", "constraint rules", "goal-driven hydration", "transitive reasoning", "export/import"],
      "tools": [
        {"name": "remember", "one_liner": "Store facts (natural language or structured)"},
        {"name": "query", "one_liner": "Query facts by pattern or natural language"},
        {"name": "forget", "one_liner": "Remove facts from memory"},
        {"name": "constrain", "one_liner": "Add constraint rules"},
        {"name": "reflect", "one_liner": "Introspect on the fact space"},
        {"name": "hydrate", "one_liner": "Goal-driven context hydration"},
        {"name": "export", "one_liner": "Export facts as JSON"},
        {"name": "import", "one_liner": "Import facts from JSON"}
      ]
    }
  ],
  "total_tools": 8,
  "total_suites": 1,
  "message": "1 tool suites with 8 tools. Showing details for 'logic' suite."
}

Cost

0 credits — pure metadata lookup.

Tips

• Use scope: "all" to see which suites are available on your server vs. the full platform
• Use focus to drill into a specific suite before calling discovery.discover with a targeted goal
• Use include_tools: true when you need tool names but not full schemas

When to use which tool