From 4c85bc7fe98619a1a5353b0b260d02c70ee2bc0a Mon Sep 17 00:00:00 2001
From: Dominic Farolino <dom@chromium.org>
Date: Tue, 26 May 2026 11:27:10 -0700
Subject: [PATCH] WebMCP: Implement tool title

Per https://github.com/webmachinelearning/webmcp/pull/152, this CL
implements the `title` property for registered tools, consistent with
MCP's tool definition [1]. This is done by adding a new `title` property
to the `ModelContextTool` dictionary for imperative tools, and a new
`tooltitle` attribute for declarative tools.

A subsequent spec PR will be made to spec the `getTools()` API and the
reflect the fact that `RegisteredTool#title` is always non-undefined,
and is the empty string when not provided on registration time, per
some discussion we had about the right API shape.

[1]:
https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool

R=masonf

Bug: 489045948
Change-Id: If848ba85ba1b4aeaa39834eca11ba91108e493c0
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7742044
Commit-Queue: Dominic Farolino <dom@chromium.org>
Reviewed-by: Mason Freed <masonf@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1636305}
---
 ...oolchange-on-attribute-mutation.https.html | 110 ++++++++++++++++++
 .../imperative/register-tool-title.https.html |  60 ++++++++++
 2 files changed, 170 insertions(+)
 create mode 100644 webmcp/declarative/toolchange-on-attribute-mutation.https.html
 create mode 100644 webmcp/imperative/register-tool-title.https.html
diff --git a/webmcp/declarative/toolchange-on-attribute-mutation.https.html b/webmcp/declarative/toolchange-on-attribute-mutation.https.html
new file mode 100644
index 00000000000000..1ee85331ed4089
--- /dev/null
+++ b/webmcp/declarative/toolchange-on-attribute-mutation.https.html
@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<meta charset="utf-8">
+<title>WebMCP: toolchange event and getTools() update on form attribute mutation</title>
+<link rel="author" href="mailto:dom@chromium.org">
+<script src="/resources/testharness.js"></script>
+<script src="/resources/testharnessreport.js"></script>
+<script src="../resources/helpers.js"></script>
+<body>
+
+<form id="f1" toolname="my_tool" tooltitle="My Title" tooldescription="desc">
+  <input id="input1" type="text" name="input_name">
+</form>
+
+<script>
+function waitForToolChange() {
+  return new Promise(resolve => {
+    navigator.modelContext.addEventListener('toolchange', resolve, { once: true });
+  });
+}
+
+promise_test(async t => {
+  const form = document.getElementById('f1');
+
+  // Wait for initial registration to complete.
+  await waitForTool('my_tool');
+
+  let tools = await navigator.modelContext.getTools();
+  assert_equals(tools.length, 1, "Initially registered tool");
+  assert_equals(tools[0].name, 'my_tool');
+  assert_equals(tools[0].title, 'My Title');
+  assert_equals(tools[0].description, 'desc');
+
+  // Test updating tooltitle attribute
+  {
+    const changePromise = waitForToolChange();
+    form.setAttribute('tooltitle', 'New Title');
+    await changePromise;
+
+    let tools = await navigator.modelContext.getTools();
+    assert_equals(tools.length, 1, "Still one tool");
+    assert_equals(tools[0].title, 'New Title', "Title is updated");
+  }
+
+  // Test updating tooldescription attribute
+  {
+    const changePromise = waitForToolChange();
+    form.setAttribute('tooldescription', 'New Description');
+    await changePromise;
+
+    let tools = await navigator.modelContext.getTools();
+    assert_equals(tools.length, 1);
+    assert_equals(tools[0].description, 'New Description', "Description is updated");
+  }
+
+  // Test updating toolname attribute
+  {
+    const changePromise = waitForToolChange();
+    form.setAttribute('toolname', 'new_tool_name');
+    await changePromise;
+
+    let tools = await navigator.modelContext.getTools();
+    assert_equals(tools.length, 1);
+    assert_equals(tools[0].name, 'new_tool_name', "Name is updated");
+  }
+
+  // Test removing tooltitle attribute (should fall back to empty string)
+  {
+    const changePromise = waitForToolChange();
+    form.removeAttribute('tooltitle');
+    await changePromise;
+
+    let tools = await navigator.modelContext.getTools();
+    assert_equals(tools.length, 1);
+    assert_equals(tools[0].title, '', "Title should fall back to empty string");
+  }
+
+  // Test removing tooldescription attribute (should unregister the tool since it's required)
+  {
+    const changePromise = waitForToolChange();
+    form.removeAttribute('tooldescription');
+    await changePromise;
+
+    let tools = await navigator.modelContext.getTools();
+    assert_equals(tools.length, 0, "Tool should be unregistered when description is removed");
+  }
+
+  // Restore the description attribute to re-register the tool
+  {
+    const changePromise = waitForToolChange();
+    form.setAttribute('tooldescription', 'Restored Description');
+    await changePromise;
+
+    let tools = await navigator.modelContext.getTools();
+    assert_equals(tools.length, 1);
+    assert_equals(tools[0].name, 'new_tool_name');
+    assert_equals(tools[0].description, 'Restored Description');
+  }
+
+  // Test removing toolname attribute (should unregister the tool since it's required)
+  {
+    const changePromise = waitForToolChange();
+    form.removeAttribute('toolname');
+    await changePromise;
+
+    let tools = await navigator.modelContext.getTools();
+    assert_equals(tools.length, 0, "Tool should be unregistered when name is removed");
+  }
+}, "Test that mutating or removing form attributes (toolname, tooldescription, tooltitle) fires toolchange and updates getTools() correctly");
+</script>
+</body>
diff --git a/webmcp/imperative/register-tool-title.https.html b/webmcp/imperative/register-tool-title.https.html
new file mode 100644
index 00000000000000..8d66238b23586d
--- /dev/null
+++ b/webmcp/imperative/register-tool-title.https.html
@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>Tool title is exposed correctly</title>
+<meta name="timeout" content="long">
+<link rel="author" href="mailto:dom@chromium.org">
+<script src="/resources/testharness.js"></script>
+<script src="/resources/testharnessreport.js"></script>
+<script src="/common/get-host-info.sub.js"></script>
+<script src="resources/helpers.js"></script>
+</head>
+<body>
+<script>
+promise_test(async () => {
+  navigator.modelContext.registerTool({
+    name: 'with-title',
+    title: 'My Custom Title',
+    description: 'tool with title',
+    execute: async () => 'empty'
+  });
+
+  const tools = await navigator.modelContext.getTools();
+  const tool = tools.find(t => t.name === 'with-title');
+
+  assert_equals(tool.title, 'My Custom Title', 'Title is preserved');
+}, 'Tool title is preserved when provided');
+
+promise_test(async () => {
+  navigator.modelContext.registerTool({
+    name: 'without-title',
+    description: 'tool without title',
+    execute: async () => 'empty'
+  });
+
+  const tools = await navigator.modelContext.getTools();
+  const tool = tools.find(t => t.name === 'without-title');
+
+  // If not provided upon registration, `title` should be empty string in the
+  // dictionary.
+  assert_equals(tool.title, '', 'Title is empty string when not provided');
+}, 'Missing tool title in registration is exposed as empty string');
+
+promise_test(async () => {
+  // \uD800 is an unpaired high surrogate.
+  navigator.modelContext.registerTool({
+    name: 'with-unpaired-surrogate',
+    title: 'Title with \uD800 unpaired surrogate',
+    description: 'tool with unpaired surrogate in title',
+    execute: async () => 'empty'
+  });
+
+  const tools = await navigator.modelContext.getTools();
+  const tool = tools.find(t => t.name === 'with-unpaired-surrogate');
+
+  // USVString replaces unpaired surrogates with U+FFFD.
+  assert_equals(tool.title, 'Title with \uFFFD unpaired surrogate');
+}, 'Tool title with unpaired surrogate is fixed up by USVString');
+</script>
+</body>
+</html>
