Skip to main content
Glama

Invoke Platform Agent Tool

talonic_invoke_agent_tool
Read-only

Call a named read-only Talonic agent tool directly with custom arguments to run data queries, field descriptions, or document reads without a model in the loop.

Instructions

Invoke ONE named tool from the platform's agent tool registry directly, with no model in the loop — you choose the arguments. This is how an external agent uses Talonic's retrieval and provenance while driving control flow itself (e.g. query_data for a read-only SQL SELECT over the extracted data, describe_data for the queryable field list, get_document_markdown to read a document's text). READ-ONLY FOR EVERY CREDENTIAL: the platform runs each caller of this route, API key or OAuth session alike, as its least-privilege viewer role, which grants only the registry's read-only tools (capability data.read). Write-capable registry tools are never invocable here, however you connected, so this tool reads and never changes workspace data. Target API: Talonic agent tool registry — https://talonic.com/docs/api (POST /v1/agent/tools/{name}/invoke; input schemas from talonic_list_agent_tools).

USE WHEN: talonic_list_agent_tools showed a tool with can_invoke: true that does what you need. Pass exactly the args its input_schema declares. NOT FOR: anything a dedicated talonic_* tool already does (prefer those — they are shaped for you).

ARGS: name (tool name), args (object matching the tool's input_schema), optional document_ids (hard scope for scope-aware tools). RETURNS: { tool, result (the tool's parsed output), citations?, artifacts?, cards? }. Denied capabilities come back as an error naming the capability required; the platform re-checks every call.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "talonic_invoke_agent_tool"
  }
}

Input Schema

NameRequiredDescriptionDefault
argsNoArguments matching the tool's input_schema.
nameYesTool name from talonic_list_agent_tools, e.g. `query_data`.
document_idsNoRestrict to these document ids (hard filter, enforced server-side).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.76

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnlyHint/destructiveHint annotations: explains least-privilege viewer enforcement for every credential, guarantees write-capable registry tools are never invocable, describes the capability-denied error format, notes server-side re-checking of every call, and sketches return shape (tool, result, citations, artifacts, cards). The idempotentHint=false is the only annotation left unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Long but front-loaded and sectioned (USE WHEN / NOT FOR / ARGS / RETURNS). Every sentence carries operational information; nothing is padding, and the critical constraint (read-only for every credential) is bolded near the top.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the RETURNS block is necessary and present, including the shape of the nested result and optional citations/artifacts/cards. Combined with the permission model and error behavior, an agent has everything needed to call this correctly on the first attempt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds that name must come from talonic_list_agent_tools, that args must match the target tool's input_schema, and that document_ids is a hard scope for scope-aware tools. Most of this restates the schema, but the scope-aware nuance and the external-schema pointer add real value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: invoke one named tool from the platform's agent tool registry, with no model in the loop. Concrete examples (query_data, describe_data, get_document_markdown) make the scope unambiguous, and it explicitly positions itself against the dedicated talonic_* siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit USE WHEN condition (talonic_list_agent_tools showed can_invoke: true) and an explicit NOT FOR clause directing the agent to prefer dedicated talonic_* tools when one exists. Prerequisite chain and argument contract are both spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.