feat: return structuredContent and advertise outputSchema for typed tools

[sd2k]

Summary

Every tool whose handler returns a concrete Go type now advertises an outputSchema reflected from that type and returns its result as structuredContent, alongside the existing text content (same JSON). Code-mode and other programmatic clients can then write code against a result's shape without calling the tool first.

Closes #1278. Part of #1281.

Changes

• tools_output.go: builds an output schema from the handler's return type in ConvertTool.
  • Results that aren't JSON objects (slices, maps) are wrapped as {"result": ...}, because MCP requires structuredContent to be an object.
  • string, any and *mcp.CallToolResult results stay text-only.
• Schemas describe the marshalled JSON, not just the Go struct, because strict clients (TS/Python SDKs) reject non-matching results:
  • nilable fields without omitempty accept null;
  • fields promoted through nil embedded pointers aren't required;
  • TextMarshaler types are strings; other json.Marshaler types are unconstrained unless they implement JSONSchema().
• Checking:
  • At construction, each schema is checked against values of its type populated to every depth. Tools are package-level MustTool vars, so a mismatch fails at startup and in every test run.
  • At call time, results are validated too, but a mismatch is logged rather than failing the call.
• Typed results for tools that returned any or model.Value, so they get schemas too:
  • query_prometheus and query_prometheus_histogram
  • the alerting operation tools
  • create_annotation

Output shape changes (for release notes)

These change what tools return compared with v2.0.0. They ship in a minor release, not as breaking changes, because tool output is not a stable API:

• query_prometheus and query_prometheus_histogram return the Prometheus API data object: {"resultType": ..., "result": ...}. The histogram tool's result field is renamed to data.
• alerting_rules_*, alerting_silences_* and alerting_manage_routing return a result struct with one field per operation. List operations report [] instead of omitting the field. Silence deletion reports silenceID instead of silence_id.
• create_annotation returns {id, message} instead of {"Payload": {...}}.

Testing

• go test ./ ./tools/... passes (unit tests).
• New tests in tools_output_test.go cover:
  • inlining, and text output matching structured output
  • nullability
  • embedded pointers
  • recursive types
  • wrapping non-object results
  • text-only result types
  • a mismatch failing at construction
• golangci-lint run: 0 issues.
• Integration tests: left to CI.

Note: this branch was originally built on v2; it's now rebased onto main after the v2.0.0 squash-merge, and still checks all 127 tools on main at construction.

[sd2k]

cursor review

[cursor]

Stale Bugbot comment from a previous run.

[sd2k]

cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit f9dfb29. Configure here.}