Skip to content

Add MCP tool annotations to smart_home example#2777

Merged
jlowin merged 1 commit into
PrefectHQ:mainfrom
bryankthompson:add-tool-annotations-example
Dec 29, 2025
Merged

Add MCP tool annotations to smart_home example#2777
jlowin merged 1 commit into
PrefectHQ:mainfrom
bryankthompson:add-tool-annotations-example

Conversation

@bryankthompson

@bryankthompson bryankthompson commented Dec 29, 2025

Copy link
Copy Markdown
Contributor

Summary

Adds ToolAnnotations to all 11 tools in the smart_home example to demonstrate proper annotation usage for AI assistants.

Changes

lights/server.py (10 tools):

  • Read-only tools (readOnlyHint=True): read_all_lights, list_groups, list_scenes, list_lights_by_group
  • Write tools (readOnlyHint=False): toggle_light, set_brightness, activate_scene, set_light_attributes, set_group_attributes

hub.py (1 tool):

  • hub_status (readOnlyHint=True)

All tools communicate with the external Hue Bridge API, so all have openWorldHint=True.

Why This Matters

MCP Tool Annotations help AI assistants understand:

  • readOnlyHint: Whether a tool modifies state (enables safer auto-execution decisions)
  • openWorldHint: Whether a tool accesses external resources (network, APIs, hardware)

This example provides educational documentation for FastMCP users on how to properly annotate their tools.

Testing

  • Syntax check passed
  • Ruff linting passed
  • All 251 tool tests pass

🤖 Generated with Claude Code

@web-flow
Add MCP tool annotations to smart_home example
c09f4a2 
Adds ToolAnnotations to all 11 tools in the smart_home example to demonstrate
proper annotation usage for AI assistants:

lights/server.py (10 tools):
- Read-only tools (readOnlyHint=True): read_all_lights, list_groups, list_scenes, list_lights_by_group
- Write tools (readOnlyHint=False): toggle_light, set_brightness, activate_scene, set_light_attributes, set_group_attributes

hub.py (1 tool):
- hub_status (readOnlyHint=True)

All tools communicate with external Hue Bridge API (openWorldHint=True).

This provides an educational example for FastMCP users on how to properly
annotate their tools to help AI assistants understand tool capabilities.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
@marvin-context-protocol marvin-context-protocol Bot added the enhancement Improvement to existing functionality. For issues and smaller PR improvements. label Dec 29, 2025
@coderabbitai

coderabbitai Bot commented Dec 29, 2025

Copy link
Copy Markdown
Contributor

Walkthrough

The pull request adds Tool Annotations to decorator definitions in the smart home example application. Specifically, ToolAnnotations from mcp.types is imported and applied to tool functions with readOnlyHint and openWorldHint parameters. Read-only operations, such as reading lights and listing groups or scenes, receive readOnlyHint=True, while write operations receive readOnlyHint=False. All tools are marked with openWorldHint=True. Additionally, error handling in some read-only tools is refined to ensure consistent return types with list[str] for error cases.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main change: adding MCP tool annotations to the smart_home example.
Description check ✅ Passed The description provides a comprehensive summary of changes, explains the rationale, details affected tools and their annotations, and includes testing confirmation. All required checklist items are marked or addressed.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9c83482 and c09f4a2.

📒 Files selected for processing (2)
  • examples/smart_home/src/smart_home/hub.py
  • examples/smart_home/src/smart_home/lights/server.py
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-12-25T15:53:07.646Z 
Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-25T15:53:07.646Z
Learning: Applies to src/fastmcp/**/*.py : Python ≥ 3.10 with full type annotations required

Applied to files:

  • examples/smart_home/src/smart_home/hub.py
  • examples/smart_home/src/smart_home/lights/server.py
🧬 Code graph analysis (2)
examples/smart_home/src/smart_home/hub.py (1)
src/fastmcp/server/server.py (3)
  • tool (1699-1713)
  • tool (1716-1730)
  • tool (1732-1815)
examples/smart_home/src/smart_home/lights/server.py (1)
src/fastmcp/server/server.py (3)
  • tool (1699-1713)
  • tool (1716-1730)
  • tool (1732-1815)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
  • GitHub Check: Run tests: Python 3.10 on ubuntu-latest
  • GitHub Check: Run tests: Python 3.13 on ubuntu-latest
  • GitHub Check: Run tests: Python 3.10 on windows-latest
  • GitHub Check: Run tests with lowest-direct dependencies
🔇 Additional comments (5)
examples/smart_home/src/smart_home/hub.py (2)

15-27: LGTM! Annotations correctly applied.

The hub_status tool is correctly annotated with readOnlyHint=True (it only checks status without modifying state) and openWorldHint=True (it communicates with the external Hue Bridge API).

1-1: No action needed. The import from mcp.types import ToolAnnotations is the correct path used consistently across the codebase in multiple files and is functioning as intended.

examples/smart_home/src/smart_home/lights/server.py (3)

50-51: LGTM! Read-only tools correctly annotated.

All read-only tools (read_all_lights, list_groups, list_scenes, list_lights_by_group) are correctly annotated with readOnlyHint=True since they only query data without modifying state, and openWorldHint=True for external Hue Bridge API communication.

Also applies to: 107-108, 120-121, 274-275

53-60: LGTM! Consistent error handling.

The error handling refinements ensure that read-only tools consistently return list[str] for both success and error cases, improving type safety and predictability.

Also applies to: 110-117, 128-129, 156-158, 282-283, 307-308

66-67: LGTM! Write tools correctly annotated.

All write tools (toggle_light, set_brightness, activate_scene, set_light_attributes, set_group_attributes) are correctly annotated with readOnlyHint=False since they modify light state, and openWorldHint=True for external Hue Bridge API communication.

Also applies to: 83-84, 161-162, 222-223, 249-250

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

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

@jlowin jlowin merged commit 30a2396 into PrefectHQ:main Dec 29, 2025
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jlowin jlowin jlowin approved these changes

Assignees

No one assigned

Labels

enhancement Improvement to existing functionality. For issues and smaller PR improvements.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@bryankthompson @jlowin @web-flow