ds2api/docs/toolcall-semantics.md

Tool call parsing semantics (Go canonical spec)

This document defines the cross-runtime contract for ParseToolCallsDetailed / parseToolCallsDetailed.

Output contract

• calls: accepted tool calls with normalized tool names.
• sawToolCallSyntax: true when tool-call-like syntax is detected (tool_calls, <tool_call>, <function_call>, <invoke>) or a valid call is parsed.
• rejectedByPolicy: true when parser extracted call syntax but all calls are rejected by allow-list policy.
• rejectedToolNames: de-duplicated rejected tool names in first-seen order.

Parse pipeline

1. Strip fenced code blocks for non-standalone parsing.
2. Build candidates from:
   • full text,
   • fenced JSON snippets,
   • extracted JSON objects around tool_calls,
   • first { to last } object slice.
3. Parse each candidate in order:
   • JSON payload parser (tool_calls, list, single call object),
   • markup parser (<tool_call>, <function_call>, <invoke>; supports attributes + nested fields).
4. Stop at first candidate that yields at least one call.

Name normalization policy

When matching parsed names against configured tools:

1. exact match,
2. case-insensitive match,
3. namespace tail match (a.b.c => c),
4. loose alnum match (remove non [a-z0-9], compare).

Standalone mode

Standalone mode (ParseStandaloneToolCallsDetailed) parses the whole input directly (no candidate slicing), while still applying:

• example-context guard,
• JSON then markup fallback,
• the same allow-list normalization policy.