Spec gap: `type: tool` graph node has no schema definition #4

New issue

Open

opened 2026-05-27 05:24:12 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:24:12 +00:00

Member

Problem

§6.2.3 defines type: function and type: tool graph nodes together, but only provides a schema for function nodes:

<node_name>:
  type: function
  function: <function_name>      # REQUIRED
  metadata: <mapping>            # OPTIONAL

For type: tool, the spec only says:

Tool nodes (type: tool) execute the named tools sequentially, populating metadata.tool_results with one entry per tool.

No YAML schema is given. The following questions are entirely unanswered:

What field specifies the tools to execute? Presumably tools:, mirroring the tool agent config (§4.5), but this is never stated.
Is tools: a list of tool names (strings), inline tool definitions (mappings), or both — same as in §4.5?
Are the same built-in tools (§4.5.1) available to a graph tool node?
Does the tool node accept a context: field?
Is safe_mode and allow_shell applicable at the node level?
What is the metadata.tool_results structure exactly? The spec says {"tool": <name>, "result": "Executed <name>"} — is result always a literal string "Executed <name>" or is it the actual tool output?

Impact on Library Implementation

The library cannot parse, validate, or execute type: tool graph nodes. Since §6.2 lists tool as a defined node type that implementations must support, this gap prevents a conformant implementation.

Fix Needed

Add a YAML schema block for type: tool nodes analogous to the function node schema, specifying:

The field(s) used to declare which tools to invoke
Whether built-in and inline tools are both supported
The exact structure of each metadata.tool_results entry (including whether result is the literal tool output or a placeholder string)

References

§6.2 — Node types table
§6.2.3 — Function and Tool Nodes
§4.5 — Tool Agents (provides the reference model for tool configuration)

## Problem §6.2.3 defines `type: function` and `type: tool` graph nodes together, but only provides a schema for `function` nodes: ```yaml <node_name>: type: function function: <function_name> # REQUIRED metadata: <mapping> # OPTIONAL ``` For `type: tool`, the spec only says: > Tool nodes (`type: tool`) execute the named tools sequentially, populating `metadata.tool_results` with one entry per tool. No YAML schema is given. The following questions are entirely unanswered: - What field specifies the tools to execute? Presumably `tools:`, mirroring the tool agent config (§4.5), but this is never stated. - Is `tools:` a list of tool names (strings), inline tool definitions (mappings), or both — same as in §4.5? - Are the same built-in tools (§4.5.1) available to a graph tool node? - Does the tool node accept a `context:` field? - Is `safe_mode` and `allow_shell` applicable at the node level? - What is the `metadata.tool_results` structure exactly? The spec says `{"tool": <name>, "result": "Executed <name>"}` — is `result` always a literal string `"Executed <name>"` or is it the actual tool output? ## Impact on Library Implementation The library cannot parse, validate, or execute `type: tool` graph nodes. Since §6.2 lists `tool` as a defined node type that implementations must support, this gap prevents a conformant implementation. ## Fix Needed Add a YAML schema block for `type: tool` nodes analogous to the `function` node schema, specifying: 1. The field(s) used to declare which tools to invoke 2. Whether built-in and inline tools are both supported 3. The exact structure of each `metadata.tool_results` entry (including whether `result` is the literal tool output or a placeholder string) ## References - §6.2 — Node types table - §6.2.3 — Function and Tool Nodes - §4.5 — Tool Agents (provides the reference model for tool configuration)

Rows
Columns

Spec gap: type: tool graph node has no schema definition #4

Problem

Impact on Library Implementation

Fix Needed

References

Spec gap: `type: tool` graph node has no schema definition #4