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, and navigate available capabilities interactively. All four 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

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
}

When to use which tool