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 ¶
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.
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}, "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).
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 ¶
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 Mismatches ¶
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.
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.