toolcatalog

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package toolcatalog assembles the tool declarations a real mast turn puts in front of a model, and states what each one promises the model it accepts. It exists so a provider adapter can be asserted against the whole catalog rather than against one hand-built fixture.

#154 was a total tool-calling outage on the Anthropic path: every tool built by ADK's functiontool.New or by internal/mcp reached Claude as a name with an empty input schema, because the converter handled only the typed genai.Schema spelling. The regression test that shipped with the fix covers functiontool.New, which is the shape of that bug rather than the shape of the bug class — the standing lesson is that hardening has to cover every construction path (#168).

So the catalog is not a list. It is **captured from a running agent**: two rigs are driven through a real ADK runner with a recording model, and what the model was handed is what gets asserted. A construction path cannot be forgotten here, because nothing enumerates them — a new tool wired into either rig's shape appears in the catalog the next time the test runs. What the rigs produce today spans the three paths that matter:

  • typed Parameters (*genai.Schema) — ADK's finish_task, and the per-sub-agent delegation tool llmagent installs on a coordinator. This is the path that always worked. transfer_to_agent, ADK's other typed-Parameters tool, is deliberately absent: mast's specialists are Task-mode and llmagent's transferTargets skips those, so no mast shape offers it, and manufacturing one to reach it would put a rig in the catalog that production never builds.
  • ParametersJsonSchema via functiontool.New — every mast-authored tool: the planner vocabulary, pause_session, the federation invoke tool. This is the path #154 broke.
  • ParametersJsonSchema via internal/mcp — an MCP server's advertised inputSchema, which is where a workload's real read and write tools come from.

The package takes no dependency on testing: it returns errors, so a caller in any test package can drive it, and the MCP endpoint is passed in rather than stood up here.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func StartStubMCP

func StartStubMCP() (endpoint string, stop func())

StartStubMCP starts an in-process streamable-HTTP MCP server and returns its endpoint plus a stop function. No network, no external process: the caller passes the endpoint to Build as Config.MCPEndpoint.

The two tools are shaped to be awkward on purpose. A converter that only ever sees {"type":"string"} properties can drop a lot and still look fine; these carry a required/optional split, an enum, an array of objects, and a nested object, which is what a real workload's MCP server advertises and what an adapter has to carry to the wire unmangled.

It lives here rather than in a test file because two provider test packages need the same fixture and neither should own it — and keeping it free of *testing.T is what lets it be shared at all.

func Summary

func Summary(catalog []Entry) string

Summary renders a catalog as one line per tool, for a failure message that says what was actually checked. A test that fails without it leaves the reader unable to tell a converter bug from a catalog that quietly stopped containing anything.

func Verify

func Verify(catalog []Entry, wire Wire) []string

Verify compares what each tool's declaration promised against what the adapter emitted, and returns one human-readable line per violation — empty when the conversion was faithful.

The comparison lives here, shared by every provider's test, so the adapters cannot drift in how strictly they are checked. A defect that one adapter is held to and another is not is how #154 survived a release: the Gemini path was fine, so nothing that ran against it would have caught the Anthropic converter dropping every schema.

What it enforces, and why each one is a real outage rather than a cosmetic mismatch:

  • Every catalogued tool is on the wire. A tool the model is never shown cannot be called.
  • A tool with arguments arrives with a non-empty properties map. This is #154 exactly: the name survives, the schema does not, and the model calls the tool with {} or does not call it at all.
  • Every argument name survives, and no name is invented. A model can only send arguments it was shown; one it was not shown is one the tool will never receive.
  • Every required argument is still marked required. Demoted to optional, it becomes an argument the model may silently omit — which surfaces as a runtime handler error, far from the cause.
  • Each argument's own schema survives as a non-empty object. A converter that lists the names but empties their types leaves the model guessing whether "limit" is a number or a sentence.

Types

type Config

type Config struct {
	// MCPEndpoint is the streamable-HTTP URL of an MCP server to
	// enumerate. Required: the MCP path is one of the three, and
	// skipping it silently would defeat the point. Callers stand up
	// an in-process server (net/http/httptest) — no network.
	MCPEndpoint string
}

Config parameterizes the rigs.

type Entry

type Entry struct {
	// Name is the function name the model calls.
	Name string
	// Spelling records which declaration field carried the schema —
	// "Parameters" (typed *genai.Schema) or "ParametersJsonSchema".
	// Reported in failures because it names the converter branch.
	Spelling string
	// Rig names the agent shape that offered this tool, so a failure
	// says where to look.
	Rig string
	// Declaration is the genai declaration ADK handed the model,
	// verbatim. This is the input a provider adapter converts.
	Declaration *genai.FunctionDeclaration
	// Props are the argument names the declaration advertises, sorted.
	// Empty means the tool genuinely takes no arguments — a fact, not
	// a hole, and the invariant treats it as one.
	Props []string
	// Required are the argument names the declaration marks required,
	// sorted. A required argument that does not survive the conversion
	// is worse than a missing optional one: the model cannot call the
	// tool at all without inventing the name.
	Required []string
}

Entry is one tool as the model was offered it, plus what its own declaration promises. Props and Required are derived from the declaration rather than written down, so the expectations cannot drift from the tools: a tool that gains an argument gains it here on the next run.

func Build

func Build(ctx context.Context, cfg Config) ([]Entry, error)

Build drives the rigs and returns the catalog, sorted by name.

A tool offered by more than one rig appears once; the declaration is the same object either way, and a duplicate would only inflate the failure output.

func (Entry) HasParams

func (e Entry) HasParams() bool

HasParams reports whether the tool advertises any arguments. Tools that do not are still catalogued — a converter that invents properties for a no-arg tool is also a defect — but the "properties must not be empty" check only applies to those that do.

type Wire

type Wire map[string]map[string]any

Wire is what a provider adapter actually put on the network, read back out of the captured request body: tool name -> the JSON schema object that tool's arguments were described by. Each adapter spells that field differently (Anthropic's input_schema, Gemini's parameters / parametersJsonSchema), so extracting it is the caller's job and comparing it is this package's.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL