feat: reduce MCP tool token usage by removing redundant docstrings

[CaliLuke]

Summary

• Remove redundant Args: sections from tool docstrings
• FastMCP already extracts parameter info from type hints into JSON schemas
• The docstring Args sections were duplicating this information, adding ~40% token bloat

Impact

• Before total: ~41.8k tokens
• After total: ~36.1k tokens
• Savings: ~5.7k tokens (~14% reduction)
• No functional changes - tools work identically
• Parameter documentation remains available via JSON schema

---

Note

^{Cursor Bugbot is generating a summary for commit 08c3873. Configure here.}

Summary by CodeRabbit

• Improvements

  • Streamlined project listing function by simplifying parameter handling.
  • Enhanced settings processing for work item property creation and updates with improved type-aware transformations.

• Documentation

  • Updated and clarified documentation across tool functions for improved clarity and usability.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Multiple tool modules in plane_mcp/tools/ have had their docstrings simplified from verbose multi-line formats to concise one-liners. Additionally, the list_projects function signature was updated to remove the workspace_slug parameter, and settings processing logic was introduced in work item property create/update functions.

Changes

Cohort / File(s)	Summary
Docstring Simplifications plane_mcp/tools/cycles.py, plane_mcp/tools/initiatives.py, plane_mcp/tools/intake.py, plane_mcp/tools/modules.py, plane_mcp/tools/users.py, plane_mcp/tools/work_items.py	Replaced multi-line docstrings with concise one-line summaries across all public tool functions. No changes to function signatures, behavior, or return types.
Projects Tool Updates plane_mcp/tools/projects.py	Simplified docstrings for all public functions. Notable change: list_projects signature updated to remove workspace_slug parameter; now accepts cursor, per_page, expand, fields, and order_by parameters only.
Work Item Properties Logic plane_mcp/tools/work_item_properties.py	Simplified docstrings across list/create/retrieve/update/delete functions. Notable change: create_work_item_property and update_work_item_property now include conditional settings processing to transform settings into TextAttributeSettings or DateAttributeSettings objects when appropriate before object construction.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Docstrings trimmed, one-liners shine,
Verbose prose now concise and fine!
Settings transform with gentle care,
Signatures refined—clean and rare!
Hopping forward, clear and bright,
Our tools now read just right!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main objective of the changeset: removing redundant docstrings to reduce token usage in MCP tool functions.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

---

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.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

plane_mcp/tools/work_item_properties.py (2)

62-73: Flag: Functional change contradicts PR objectives.

The PR objectives state "No functional changes; tools are expected to work identically," but lines 62-73 introduce new settings processing logic that converts generic dict settings into type-specific TextAttributeSettings or DateAttributeSettings objects based on the property_type.

While this may be a useful enhancement, it represents a behavioral change that should either be:

1. Documented in the PR description as an intentional improvement, or
2. Moved to a separate PR focused on functional enhancements

---

131-142: Flag: Functional change contradicts PR objectives.

Similar to the create_work_item_property function, lines 131-142 introduce new settings processing logic that wasn't present before. This conditional transformation of settings based on property_type is a functional change that contradicts the PR's stated objective of having "No functional changes."

Consider moving this enhancement to a separate PR or updating the PR description to document this behavioral change.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 754faa9 and 08c3873.

📒 Files selected for processing (8)

• plane_mcp/tools/cycles.py
• plane_mcp/tools/initiatives.py
• plane_mcp/tools/intake.py
• plane_mcp/tools/modules.py
• plane_mcp/tools/projects.py
• plane_mcp/tools/users.py
• plane_mcp/tools/work_item_properties.py
• plane_mcp/tools/work_items.py

🧰 Additional context used

🧬 Code graph analysis (4)

plane_mcp/tools/modules.py (1)

plane_mcp/client.py (1)

• get_plane_client_context (21-73)

plane_mcp/tools/cycles.py (1)

plane_mcp/client.py (1)

• get_plane_client_context (21-73)

plane_mcp/tools/intake.py (1)

plane_mcp/client.py (1)

• get_plane_client_context (21-73)

plane_mcp/tools/projects.py (1)

plane_mcp/client.py (1)

• get_plane_client_context (21-73)

⏰ 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). (1)

• GitHub Check: Cursor Bugbot

🔇 Additional comments (13)

plane_mcp/tools/users.py (1)

13-16: LGTM! Docstring simplification aligns with PR objectives.

The simplified docstring is clear and concise. FastMCP's automatic schema generation from type hints ensures parameter documentation remains available.

plane_mcp/tools/intake.py (5)

21-35: LGTM! Clear and concise docstring.

The simplified docstring effectively describes the function's purpose. Parameter documentation is handled by FastMCP's schema generation from type hints.

---

38-49: LGTM! Documentation streamlined appropriately.

The one-line docstring is sufficient, and parameter details remain accessible through the generated JSON schema.

---

52-69: LGTM! Docstring clarifies work item ID usage.

The simplified docstring helpfully notes that the issue field should be used, not the intake work item ID, which is valuable guidance for users.

---

72-87: LGTM! Consistent simplification.

The docstring maintains the important clarification about using the work item ID from the issue field.

---

90-95: LGTM! Delete operation clearly documented.

The simplified docstring includes the necessary clarification about which ID to use.

plane_mcp/tools/modules.py (1)

24-33: LGTM! Consistent docstring simplification across module tools.

All module-related tool docstrings have been appropriately simplified. The one-line descriptions are clear, and parameter documentation remains available through FastMCP's type hint extraction.

plane_mcp/tools/initiatives.py (1)

21-29: LGTM! Initiative tools documented concisely.

The docstring simplifications are consistent with the PR objectives. All initiative operations have clear, concise descriptions that align with the pattern used across other tool modules.

plane_mcp/tools/cycles.py (1)

24-33: LGTM! Comprehensive docstring simplification for cycle tools.

All 12 cycle-related tool functions have been appropriately simplified with clear, concise one-line docstrings. The changes are consistent with the PR's token reduction objectives while maintaining clarity.

plane_mcp/tools/projects.py (2)

50-218: Docstring simplifications look good.

The simplified one-line docstrings for all project tool functions maintain clarity while reducing token usage, which aligns perfectly with the PR objectives. Since FastMCP extracts parameter information from type hints, the verbose Args: sections were indeed redundant.

---

24-30: No action needed—this is an MCP tool with no internal Python callers to update.

The list_projects function is an MCP tool decorated with @mcp.tool() and exposed through the FastMCP framework, not a regular function with internal callers. It's consumed by external clients through the MCP protocol interface rather than direct Python calls. Removing workspace_slug from the signature in favor of obtaining it from context (line 32) is the correct architectural approach for MCP tools and does not require updating internal callers.

plane_mcp/tools/work_items.py (1)

22-241: LGTM! Docstring simplifications are consistent and clear.

All work item tool functions have been updated with concise one-line docstrings that maintain clarity. The addition of the example format "(e.g., MP-123)" in retrieve_work_item_by_identifier is a nice touch that improves usability. No functional changes were introduced.

plane_mcp/tools/work_item_properties.py (1)

27-39: Docstring simplifications look good.

The simplified one-line docstrings for list_work_item_properties, retrieve_work_item_property, and delete_work_item_property maintain clarity while reducing token usage, consistent with the PR objectives.

Also applies to: 96-108, 168-180

[CaliLuke]

Thanks for the review @coderabbitai!

Regarding the flagged "functional changes" in work_item_properties.py (lines 62-73 and 131-142):

These are not new changes - the settings processing logic was already present in the canary branch before this PR. The git diff confirms only docstring changes were made:

git diff canary -- plane_mcp/tools/work_item_properties.py

Shows only docstring removals - the # Convert settings dict to appropriate settings object if needed blocks are unchanged from the base branch. The PR description's claim of "No functional changes" is accurate.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify that only docstring changes were made to work_item_properties.py
git diff canary -- plane_mcp/tools/work_item_properties.py

Length of output: 6004

---

@CaliLuke, you're absolutely right, and I apologize for the error in my analysis!

The git diff confirms that only docstring changes were made to work_item_properties.py. The settings processing logic at those line ranges was indeed already present in the canary branch and is not part of this PR. My AI summary incorrectly flagged those blocks as new changes introduced by this PR.

The PR accurately contains only documentation changes - removing verbose Args: and Returns: sections from docstrings across all the tool files. Your claim of "No functional changes" is correct.

Thank you for the clarification! ✨

[Prashant-Surya]

Let's not remove this docstring. Fields in search are little complicated and this docstring helps with that.

Please verify other tools as well once before removing all the docstrings

[CaliLuke]

Do you have an eval for the search mcp? I've been using my version of the mcp with Claude since I submitted the PR and I have observed no confusion or loss of performance. Can we perhaps leave a shorter set of instructions?