Repository navigation
MCP: Describe tool side effects and retry behavior #2636
Description
Publish accurate hints about whether each tool reads data, changes or deletes data, can be repeated safely, or contacts an external provider. Clients use these hints to explain operations and guide their behavior.
This independent follow-up under #2408 changes tool metadata only. Review actual behavior, including generated IDs and embedding or reranking calls. A hint does not enforce permission checks or make retries safe.
This ticket is done when registry tests verify representative read, write, destructive, and provider-calling tools. The advertised hints must match behavior, and tool execution must remain unchanged.
Status on October 23, 2026
PR #2649 implements this and is still open in the MCP stack. All 35 tools publish read-only, destructive, idempotency and external-interaction hints, and an independent test checks them. The combined stack passed 381 focused tests locally. It has no CI run yet because it does not target main.
Implementation requirements and source references
Tracking issue: #2408.
Tracking correspondence: Related changelog IDs are listed below. This is an independent follow-up, outside the launch milestone unless promoted for a demonstrated release blocker. Shared requirement IDs remain stable across the delivery plan and #2408.
Why
The existing MCP tools do not publish behavior hints that help clients distinguish a read from a write or a destructive operation. Clients also cannot tell from those hints whether a repeated call is safe or whether the tool may contact an external embedding/reranking service.
These annotations are optional client guidance. Adding them is not required to upgrade to Quarkiverse 2.0.3, and they do not replace authorization.
Work
- Review the existing tools and explicitly set accurate read-only, destructive, idempotency, and external-interaction hints.
- Base each hint on actual behavior. Account for generated IDs, data mutations, and embedding/reranking calls.
- Keep the change limited to tool metadata.
Done when
Registry tests verify representative read, write, destructive, and provider-calling tools. The advertised hints match their behavior and tool execution is unchanged.
This is an independent follow-up under #2408. It is separate from #2631, which fixes the shape of update arguments.
Modern protocol and OAuth acceptance details
Review retry consequences after broken streams. A new JSON-RPC ID does not deduplicate a mutation, and idempotentHint does not enforce idempotency. Do not mark generated-ID inserts or side-effecting provider calls safe to replay without evidence. Keep annotations as optional guidance, never a substitute for authorization or execution safeguards.
Changelog traceability
- M9 Remove stream redelivery, lines 28 — Required.
Normative detail: Streamable HTTP, authorization, caching.
Required base protocol/schema behavior remains owned by #2625 and verified by #2626. This follow-up owns only its stated enhancement or proven gap.
Activity
[-]Add accurate behavior annotations to MCP tools[/-][+]MCP: Add accurate tool behavior annotations[/+][-]MCP: Add accurate tool behavior annotations[/-][+]MCP: Describe tool side effects and retry behavior[/+]