From b7e2d4694ba08ad0ff7ca24f8e9b0bc94c794350 Mon Sep 17 00:00:00 2001 From: Naveen Chatlapalli Date: Mon, 14 Sep 2026 22:29:42 -0500 Subject: [PATCH 1/2] Document dynamic tool definition patterns (#167) --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index fb3db48..ffc08fb 100644 --- a/README.md +++ b/README.md @@ -436,6 +436,14 @@ Designing tools for AI agents requires different considerations than building tr - **Default to static registration for simple apps**: For simpler web applications with a handful of tools, static registration on page load is recommended. Dynamic lifecycle management is most valuable for complex, multi-state applications. - **Trust the agent**: Frame tool descriptions around what the tool accomplishes and what inputs it requires, rather than trying to enforce rigid step-by-step procedural chains through prompt text. +### Keep Dynamic Tool Definitions Current + +- **Delegate changing behavior through the registered callback**: If a tool's name, description, and schema remain accurate, its `execute` callback can read current application state or call a mutable implementation reference. The tool does not need to be re-registered merely because its implementation changes. +- **Re-register changed agent-facing metadata**: To change a tool's name, description, or input schema, abort the signal used for its registration and register the replacement definition. Unregistration and registration each produce a `toolchange` event; consumers that observe the event can refresh their tool list, while other consumers may enumerate tools on their own schedule. +- **Revalidate at execution time**: A discovered schema describes the tool when it was observed, but application state can change before invocation. The `execute` callback must still validate current inputs, authorization, and workflow preconditions before performing the action. + +WebMCP does not currently define an in-place `updateTool()` method, lazy schemas, or disabled and grouped tool states. Those potential additions remain under discussion in [issue #167](https://github.com/webmachinelearning/webmcp/issues/167) and [issue #255](https://github.com/webmachinelearning/webmcp/issues/255). + ### Clear Language and Semantic Naming - **Precise verbs and distinctions**: Distinguish immediate execution from initiating a workflow (e.g., `create-event` to immediately book an event vs. `start-event-creation` to navigate to an event form). From 1a18d114c094f62fcf89bd915c5f9007c8b68f59 Mon Sep 17 00:00:00 2001 From: Dominic Farolino Date: Tue, 29 Sep 2026 11:32:05 -0400 Subject: [PATCH 2/2] Some nits and rewording --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ffc08fb..8bd200a 100644 --- a/README.md +++ b/README.md @@ -436,13 +436,13 @@ Designing tools for AI agents requires different considerations than building tr - **Default to static registration for simple apps**: For simpler web applications with a handful of tools, static registration on page load is recommended. Dynamic lifecycle management is most valuable for complex, multi-state applications. - **Trust the agent**: Frame tool descriptions around what the tool accomplishes and what inputs it requires, rather than trying to enforce rigid step-by-step procedural chains through prompt text. -### Keep Dynamic Tool Definitions Current +### Keeping agent-facing parts of a tool definition updated -- **Delegate changing behavior through the registered callback**: If a tool's name, description, and schema remain accurate, its `execute` callback can read current application state or call a mutable implementation reference. The tool does not need to be re-registered merely because its implementation changes. -- **Re-register changed agent-facing metadata**: To change a tool's name, description, or input schema, abort the signal used for its registration and register the replacement definition. Unregistration and registration each produce a `toolchange` event; consumers that observe the event can refresh their tool list, while other consumers may enumerate tools on their own schedule. -- **Revalidate at execution time**: A discovered schema describes the tool when it was observed, but application state can change before invocation. The `execute` callback must still validate current inputs, authorization, and workflow preconditions before performing the action. +- **A tool's implementation can by dynamic**: As long as a tool's name, description, and input schema remain accurate, its `execute` callback can delegate to another function that an application can change over time. The tool does not need to be re-registered merely because its implementation changes. +- **Re-register changed agent-facing metadata**: A tool's name, description, and input schema are loaded into the model's context statically. To change them, unregister the tool and re-register it with update information for the model to consume. Unregistration and registration each produce a `toolchange` event; consumers that observe the event can refresh their tool list accordingly. +- **Validation at execution time**: A tool's input schema is consumed by the model when the tool was first observed, but application state can change before the tool is invoked. The tool's `execute` callback should still validate current inputs, authorization, and preconditions before running. -WebMCP does not currently define an in-place `updateTool()` method, lazy schemas, or disabled and grouped tool states. Those potential additions remain under discussion in [issue #167](https://github.com/webmachinelearning/webmcp/issues/167) and [issue #255](https://github.com/webmachinelearning/webmcp/issues/255). +WebMCP does not currently define an in-place `updateTool()` method, lazy schemas, or disabled and grouped tool states. See [issue #167](https://github.com/webmachinelearning/webmcp/issues/167) and [issue #255](https://github.com/webmachinelearning/webmcp/issues/255) for more discussion. ### Clear Language and Semantic Naming