toolsurface

package
v1.164.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package toolsurface holds what each platform tool advertises in tools/list that a client decides by: the verbs an action tool's schema enumerates, and whether a tool reads, writes, or can remove or overwrite.

Two places assert these tables. The acceptance criteria of #1692 and #1827 read them through a real client against a running platform, in the E2E Nightly; TestRealDB_AdvertisedSurfaceMatchesTheTables (pkg/platform) reads them against the tools/list of a platform with every toolkit assembled, in the real-database gate every pull request runs. #2515 added two verbs to manage_feedback and the tables stayed behind; only the nightly saw it, after a release tag had been refused (#2521).

Index

Constants

This section is empty.

Variables

View Source
var ActionEnums = map[string][]string{
	"manage_asset": {
		verbList, verbGet, "update", verbDelete, "list_versions", "revert", "search", "provenance", "patch",
		"locate", "get_content", "outline", "stats", "diff", "share", "list_shares", "revoke_share",
		"create_collection", "list_collections", "get_collection", "update_collection",
		"delete_collection", "set_sections",
	},
	"manage_feedback": {"create", verbList, verbGet, "reply", "resolve", "request_validation", "respond_validation", "edit", verbDelete},

	"s3_object": {verbGet, "metadata", "put", "copy", verbDelete, "presign"},
	"notify":    {verbList, "send", "publish"},
	// contains filtered or unexported fields
}

ActionEnums are the verbs each action tool's schema advertises (#1827), each written as the tool advertises it.

View Source
var Annotations = map[string]Expectation{

	"platform_info":       {ReadOnly: true},
	"platform_find_tools": {ReadOnly: true},
	"list_connections":    {ReadOnly: true},
	"search":              {ReadOnly: true},
	"fetch":               {ReadOnly: true},
	"show_prompts":        {ReadOnly: true},
	"show_scripts":        {ReadOnly: true},
	"api_discover":        {ReadOnly: true},
	"graphql_discover":    {ReadOnly: true},
	"s3_list":             {ReadOnly: true},

	"apply_knowledge": {Destructive: true},
	"memory_capture":  {Destructive: true},

	"manage_asset":        {Destructive: true},
	"manage_table":        {Destructive: true},
	"manage_resource":     {Destructive: true},
	"manage_prompt":       {Destructive: true},
	"manage_script":       {Destructive: true},
	"run_script":          {Destructive: true},
	"api_invoke_endpoint": {Destructive: true},
	"graphql_query":       {Destructive: true},
	"s3_object":           {Destructive: true},
	"manage_schema":       {Destructive: true},
	"manage_application":  {Destructive: true},
	"manage_site":         {Destructive: true},

	"save_asset": {Destructive: false},
	"notify":     {Destructive: false},

	"manage_feedback": {Destructive: true},

	"manage_approval": {Destructive: false},
	"trino_export":    {Destructive: false},
	"api_export":      {Destructive: false},
	"graphql_export":  {Destructive: false},

	"trino_query":            {ReadOnly: true},
	"trino_explain":          {ReadOnly: true},
	"trino_browse":           {ReadOnly: true},
	"trino_describe_table":   {ReadOnly: true},
	"trino_list_connections": {ReadOnly: true},
	"trino_execute":          {Destructive: true},
	// contains filtered or unexported fields
}

Annotations classifies every tool this repository registers. A native tool in tools/list and absent from this table is a failure, so a toolkit added later cannot ship without the decision being made (#1692).

View Source
var VerbArg = map[string]string{/* contains filtered or unexported fields */}

VerbArg is the argument a tool names its verb in, where it is not "action".

Functions

func Destructive

func Destructive(tool *mcp.Tool) (value, present bool)

Destructive reports what a listed tool says about destructiveHint. The field is a pointer because the specification's default when it is absent is true, so "unset" and "false" are different answers.

func Enum

func Enum(schema any, arg string) ([]string, error)

Enum reads one property's enum out of an advertised input schema.

func Mismatches

func Mismatches(tools []*mcp.Tool) []string

Mismatches compares a tools/list with both tables and returns one sentence per disagreement, sorted. A tool in ActionEnums that the listing does not carry is a mismatch too: the caller lists a platform built to register it.

func Native

func Native(tools []*mcp.Tool) []*mcp.Tool

Native returns the tools this repository is answerable for: the listing less the gateway's proxied upstream tools, whose names carry the "__" separator and whose annotations are the upstream's.

func VerbArgOf

func VerbArgOf(tool string) string

VerbArgOf is the argument the named tool takes its verb in.

Types

type Expectation

type Expectation struct {
	ReadOnly bool
	// Destructive is read only when ReadOnly is false, which is the condition
	// the MCP specification puts on destructiveHint.
	Destructive bool
}

Expectation is what one tool must advertise: whether it can modify state, and when it can, whether any of its actions removes or overwrites state that is already there.

Jump to

Keyboard shortcuts

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