mcp-server-polarion: Skill for Claude Code

Shrink Tool Descriptions

Goal: minimize chars (tokens) shipped to client LLM through @mcp.tool descriptions — tool description (whole docstring) and Field(description=...) param descriptions — push to failure boundary while keeping eval gate GREEN. Run as compress → eval → compress loop: probe boundary, adopt last GREEN before it. RED never committed — RED mean "one cut too far."

Be deliberate. One tool at a time. Each cut small delta from current GREEN, never jump to absolute terse form. Snapshot before every cut. On RED, bisect cut set — never full-revert to original (net-zero trap). Reproduce RED before trusting it (min_pass_rate=1.0 make single RED possibly noise).

What actually ships to the LLM (reprove every run — Step 0)

Repo does not use Google-style Args:/Returns: docstrings. Verified surfaces:

• Tool description = ENTIRE docstring. No section stripped — whole prose ships. Primary target; editing it docstring-only.
• Param descriptions = Field(description=...) in signature, NOT docstring. Ship in input schema (properties[p].description); docstring edit cannot touch them.
• No Returns:/Raises:/Example: blocks exist to strip — no free text there to delete.

Don't trust list blind — reprove with Step-0 dump each run; refactor or FastMCP change can move text between surfaces.

Two scopes

• Scope A — docstring-only (default). Compress docstring prose → tool description. Signature untouched. Fully honors "signature/return/logic unchanged."
• Scope B — Field-description pass (opt-in; needs explicit operator go-ahead). Also compress Field(description=...) strings. Touch only description= string — never type, default, min_length/max_length, or validators. Params often big share of LLM-facing chars (~40% on param-heavy tools, per Step-0 dump), so Scope B roughly doubles reachable savings.

If operator not opted into Scope B, every Field(description=...) no-op for your edits — exclude from reducible baseline, report as such.