feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

Adds MCP tool annotations (destructiveHint, title) to all 26 chart generation tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

• Added destructiveHint: true to all 26 chart generation tools
• Added title annotations for human-readable display (e.g., "Generate Line Chart", "Generate Pie Chart")

All chart tools are marked as destructive because they create/generate visual outputs, which constitutes a write operation from the MCP client's perspective.

Tools Annotated

Tool Name	Title
generate_area_chart	Generate Area Chart
generate_bar_chart	Generate Bar Chart
generate_boxplot_chart	Generate Boxplot Chart
generate_column_chart	Generate Column Chart
generate_district_map	Generate District Map
generate_dual_axes_chart	Generate Dual Axes Chart
generate_fishbone_diagram	Generate Fishbone Diagram
generate_flow_diagram	Generate Flow Diagram
generate_funnel_chart	Generate Funnel Chart
generate_histogram_chart	Generate Histogram Chart
generate_line_chart	Generate Line Chart
generate_liquid_chart	Generate Liquid Chart
generate_mind_map	Generate Mind Map
generate_network_graph	Generate Network Graph
generate_organization_chart	Generate Organization Chart
generate_path_map	Generate Path Map
generate_pie_chart	Generate Pie Chart
generate_pin_map	Generate Pin Map
generate_radar_chart	Generate Radar Chart
generate_sankey_chart	Generate Sankey Chart
generate_scatter_chart	Generate Scatter Chart
generate_treemap_chart	Generate Treemap Chart
generate_venn_chart	Generate Venn Chart
generate_violin_chart	Generate Violin Chart
generate_waterfall_chart	Generate Waterfall Chart
generate_word_cloud_chart	Generate Word Cloud Chart

Why This Matters

• Annotations provide semantic metadata that helps MCP clients understand tool behavior
• Clients can make better decisions about when to use tools and in what order
• Enables safer tool execution by distinguishing read-only from destructive operations
• Human-readable titles improve tool discoverability and UI display

Testing

• Server builds successfully (npm run build)
• Lint passes (biome check)
• Live verification: Started server and confirmed tools/list returns annotations for all 26 tools
• Annotation values match actual tool behavior (all generation = destructive)

🤖 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 introduces significant metadata enhancements for all 26 chart generation tools. By adding title and destructiveHint annotations, the changes aim to improve the interpretability and safe execution of these tools by Large Language Models and Multi-Client Platform clients. This ensures that clients can make more intelligent decisions regarding tool usage and interaction.

Highlights

• Tool Annotations Added: Added destructiveHint: true and human-readable title annotations to all 26 chart generation tools. These annotations provide semantic metadata to improve LLM understanding and client decision-making.
• Destructive Hint: All chart generation tools are now explicitly marked as destructive, as they produce visual outputs which are considered write operations from the MCP client's perspective. This enables safer tool execution.
• Improved LLM Understanding: The new annotations help LLMs better understand tool behavior, leading to more informed choices about when and how to use these tools, and enhancing tool discoverability in UIs.

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 title and destructiveHint annotations to all 26 chart generation tools, which is a valuable enhancement for improving how LLMs understand and use these tools. The implementation is correct and achieves the goal. My main feedback is regarding code duplication. The same annotations block is added to every tool definition. I've left a comment on src/charts/area.ts with a suggestion to refactor this into a shared utility function to improve long-term maintainability. This could be handled in a follow-up PR. Otherwise, the changes look good.

[hustcc]

@triepod-ai why need to add destructiveHint: true？

[bryankthompson]

Great question! You're right.

I've updated the PR to use readOnlyHint: true instead. Chart generation tools are pure transformations (data → visualization) that don't modify external state, so they should be marked as read-only.

Thank you for the feedback!

[hustcc]

@triepod-ai help to fix the ci.

[bryankthompson]

Hi @hustcc, thanks for the feedback!

I've pushed a fix that updates all 26 test fixture JSON files to include the annotations field. The tests now pass locally:

 ✓ __tests__/charts/charts.spec.ts (26 tests) 5ms
 Test Files  6 passed (6)
      Tests  42 passed (42)

The CI workflow is waiting for approval (first-time contributor from fork). Once approved, it should pass.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.02%. Comparing base (e5e35c1) to head (16acb8f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #249      +/-   ##
==========================================
+ Coverage   79.97%   81.02%   +1.05%     
==========================================
  Files          42       42              
  Lines        1878     1982     +104     
  Branches       31       31              
==========================================
+ Hits         1502     1606     +104     
  Misses        374      374              
  Partials        2        2              

Files with missing lines	Coverage Δ
src/charts/area.ts	100.00% <100.00%> (ø)
src/charts/bar.ts	100.00% <100.00%> (ø)
src/charts/boxplot.ts	100.00% <100.00%> (ø)
src/charts/column.ts	100.00% <100.00%> (ø)
src/charts/district-map.ts	100.00% <100.00%> (ø)
src/charts/dual-axes.ts	100.00% <100.00%> (ø)
src/charts/fishbone-diagram.ts	100.00% <100.00%> (ø)
src/charts/flow-diagram.ts	100.00% <100.00%> (ø)
src/charts/funnel.ts	100.00% <100.00%> (ø)
src/charts/histogram.ts	100.00% <100.00%> (ø)
... and 16 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.