feat(mcp): Add tool annotations for improved LLM tool understanding

[triepod-ai]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint) to all 15 tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

This is an unsolicited contribution to improve the MCP ecosystem. No existing issue to reference.

✅ Checklist

• I have followed every step in the contributing guide
• The PR title follows the convention (feat(mcp): ...)
• I ran and tested the code works

Testing

1. Build verification: TypeScript compiles without errors

   pnpm build [email protected]/cli-v3

2. Annotation format verification: Confirmed annotations follow MCP specification:

   • readOnlyHint: true for read-only tools (queries, fetches, lists)
   • destructiveHint: true for state-modifying tools (create, deploy, cancel)

3. Live verification pending: Full MCP client integration testing requires environment setup with API credentials

Changelog

• Added readOnlyHint: true to 10 read-only tools:

  • searchDocsTool, listOrgsTool, listProjectsTool, getCurrentWorker
  • listRunsTool, getRunDetailsTool, waitForRunToCompleteTool
  • listDeploysTool, listPreviewBranchesTool

• Added destructiveHint: true to 5 state-modifying tools:

  • createProjectInOrgTool, initializeProjectTool, triggerTaskTool
  • cancelRunTool, deployTool

• Updated registerTool() in tools.ts to pass annotation fields

Why This Matters

• Annotations provide semantic metadata that helps LLMs understand tool behavior
• LLMs can make better decisions about when to use tools and in what order
• Enables safer tool execution by distinguishing read-only from destructive operations
• Follows the MCP Tool Annotations specification

Screenshots

N/A - metadata-only changes with no UI impact

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6161130

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

The pull request adds two new metadata fields—readOnlyHint and destructiveHint—to tool definitions across multiple files in the CLI-v3 MCP tools package. These fields are added to tools in deploys.ts, docs.ts, orgs.ts, previewBranches.ts, runs.ts, and tasks.ts, with read-only operations marked as (true, false) and state-mutating operations marked as (false, true). The base tool registration payload in tools.ts is also extended to support these annotation fields. No functional logic, control flow, or error handling is altered.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding tool annotations (readOnlyHint and destructiveHint) to MCP tools for improved LLM understanding.
Description check	✅ Passed	PR description is comprehensive and well-structured, addressing all key template sections with detailed information about changes, testing, and rationale.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.