feat: add MCP tool annotations to 14 tools

[triepod-ai]

Description

Add MCP tool annotations to 14 tools that were missing them. Tool annotations help MCP clients (like Claude) make better decisions about tool safety and behavior characteristics.

Changes Made

• Added readOnlyHint: True annotations to 14 analysis tools
• Added openWorldHint: True to apilookup (searches external docs)
• Added Optional import where needed (consensus.py, planner.py, apilookup.py)
• No breaking changes
• No new dependencies

Tools Annotated

Tool	Annotations	Description
analyze	readOnlyHint: True	Code analysis workflow
apilookup	readOnlyHint: True, openWorldHint: True	API documentation lookup
challenge	readOnlyHint: True	Critical thinking analysis
codereview	readOnlyHint: True	Code review workflow
consensus	readOnlyHint: True	Multi-model consensus building
debug	readOnlyHint: True	Debugging and root cause analysis
docgen	readOnlyHint: True	Documentation generation
planner	readOnlyHint: True	Task planning workflow
precommit	readOnlyHint: True	Git change validation
refactor	readOnlyHint: True	Refactoring analysis
secaudit	readOnlyHint: True	Security audit
testgen	readOnlyHint: True	Test generation
thinkdeep	readOnlyHint: True	Deep thinking analysis
tracer	readOnlyHint: True	Code tracing

All these tools perform read-only analysis without modifying files, making readOnlyHint: True appropriate.

Testing

• Follows existing annotation pattern from chat.py, version.py, listmodels.py, clink.py
• Changes are minimal (adding single method per file)
• No functional changes to tool behavior

Note: This is a metadata-only change that adds hints for MCP clients. The annotation infrastructure already exists in server.py and is used by existing tools.

Related Issues

N/A - Enhancement to improve MCP client integration

Checklist

• PR title follows the format guidelines above
• Self-review completed
• Documentation: Annotations are self-documenting via docstrings
• Ready for review

Additional Notes

This PR brings tool annotation coverage to 18/18 tools (100%), up from 4/18 (22%). Tool annotations are part of the MCP specification and help clients understand tool behavior without executing them.

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @triepod-ai, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the metadata available for various tools by implementing MCP (Multi-Client Protocol) annotations. These annotations provide crucial hints to clients, such as Claude, enabling them to make more informed decisions regarding tool safety and operational characteristics. The changes are purely metadata-driven, ensuring no functional alterations to the tools themselves, and complete the annotation coverage for all existing tools.

Highlights

• MCP Tool Annotations: Added readOnlyHint: True annotations to 14 analysis tools, signifying their non-modifying nature.
• External Search Indication: Introduced openWorldHint: True to the apilookup tool, indicating its capability to search external documentation sources.
• Type Hint Imports: Included the Optional type hint import in apilookup.py, consensus.py, and planner.py to support the new annotation methods.
• Annotation Coverage: Achieved 100% MCP tool annotation coverage across all 18 tools, significantly increasing from the previous 22%.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds MCP tool annotations to 14 tools, which is a great enhancement for MCP clients. The changes are consistent and correctly implement the get_annotations method for each tool, adding readOnlyHint and openWorldHint where appropriate. The necessary Optional imports are also included.

I have one suggestion for a minor improvement regarding performance and code style, which I've detailed in a comment on tools/analyze.py. The suggestion is to define the annotation dictionary as a class-level constant to avoid its recreation on every method call. This pattern could be applied to all 14 modified tools for consistency.

[gemini-code-assist]

For a minor performance optimization and to establish a consistent pattern for constants, you could define the annotation dictionary as a class-level constant. This prevents creating a new dictionary every time get_annotations() is called. While the performance impact is likely small, this pattern can improve code clarity and is a good practice, especially if this method is called frequently.

This suggestion applies to all 14 tools modified in this PR.

Here's how you could implement it for AnalyzeTool:

class AnalyzeTool(WorkflowTool):
    _ANNOTATIONS = {"readOnlyHint": True}

    # ... other methods ...

    def get_annotations(self) -> Optional[dict[str, Any]]:
        """Return tool annotations indicating this is a read-only analysis tool."""
        return self._ANNOTATIONS

[triepod-ai]

Thanks for the feedback @gemini-code-assist! Great suggestion on using class-level constants.

I've updated all 14 tools to define _ANNOTATIONS as class-level constants:

class AnalyzeTool(WorkflowTool):
    _ANNOTATIONS: dict[str, Any] = {"readOnlyHint": True}

    def get_annotations(self) -> Optional[dict[str, Any]]:
        return self._ANNOTATIONS

This pattern:

• Avoids creating new dictionaries on each get_annotations() call
• Makes annotations visible at the class definition level
• Establishes a consistent pattern across all tool classes

All 14 files have been updated with this approach.

[gemini-code-assist]

That's an excellent implementation, @triepod-ai! Using class-level constants for _ANNOTATIONS is indeed a great approach. I agree with your points that it effectively avoids redundant dictionary creation, enhances visibility at the class level, and promotes a consistent pattern across your tool classes. Thanks for the update!