registerTool should return registered tool instead of undefined

[beaufortfrancois]

When registering and executing tools, I often see boilerplate code that requires an extra call to getTools().

await document.modelContext.registerTool({
  name: "tool",
  description: "A tool",
  execute: () => {},
});

const [tool] = await document.modelContext.getTools();
await document.modelContext.executeTool(tool, "{}");

Could we simplify this workflow by having registerTool() return the registered tool object directly? That way, we can pass it straight into executeTool() without the extra lookup step (which is not required by the way).

const tool = await document.modelContext.registerTool({
  name: "tool",
  description: "A tool",
  execute: () => {},
});

await document.modelContext.executeTool(tool, "{}");

[domfarolino]

We could support this, but I have two hesitations:

1. Do developers need this pattern? Outside of toy apps & tests, when do you register a tool and invoke it in the same script? Real use cases are more likely to register a tool independently from an agent harness calling getTools() at various times. The command (registerTool()) and query (getTools()) are separated.
2. Would this violate Command Query Separation?

CQS is basically two separate rules:

1. Queries should have no side effects
2. Commands should return nothing

Rule 1 lets you treat any value-returning expression as safe to reorder and reason about in isolation, but it doesn't apply here. Rule 2 is argued for in https://w3ctag.github.io/design-principles/#void-functions, but that seems to mostly apply to methods that return a synchronous value; since ours returns a Promise—especially one that developers already have to consider might reject—I don't think resolving it to a Tool object carries the same backwards compatibility / chaining risk.

So it feels like if we upheld rule (2) (enforced Promise<undefined>), we'd be doing so just for the sake of purity, at the cost of forcing another query to get access to the tool you just registered.

That actually brings up another principle through which to analyze this: what is the cost of obtaining the side effect of the command, and do you already have access to it? If we were designing appendChild() from scratch today, we'd make it return undefined for the reasons cited in https://w3ctag.github.io/design-principles/#void-functions, and because the caller already has access to the return data—nothing supports it returning a node.

But in our case, especially if getTools() resolves to transferrable Tool interface objects constructed from the developer's input, then the resolution to Tool object would actually be something the caller doesn't already have. The resolution saves them a separate round-trip call to getTools(), and I don't see any risk of backwards compatibility.

Let me get some more opinions, since I want to make sure if we do this, we're not flouting a design principle I'm not fully anticipating the value of.