Skip to content

docs: improve tool descriptions for better AI agent selection#3491

Closed
teehooai wants to merge 1 commit intomodelcontextprotocol:mainfrom
teehooai:improve-tool-descriptions
Closed

docs: improve tool descriptions for better AI agent selection#3491
teehooai wants to merge 1 commit intomodelcontextprotocol:mainfrom
teehooai:improve-tool-descriptions

Conversation

@teehooai
Copy link

@teehooai teehooai commented Mar 8, 2026

Summary

Add scenario triggers ("Use when...") and disambiguation guidance to tool descriptions in git and memory servers.

AI agents select tools based on description text. Current descriptions are minimal and give agents no guidance on when to use each tool vs similar alternatives.

Example change (git_status):

Before:

Shows the working tree status

After:

Show the working tree status including modified, staged, and untracked files. Use when the user wants to see the current state of the repository before committing or staging changes.

Changes

  • git server (12 tools): Add "Use when" triggers and disambiguation between similar tools (e.g., git_diff_unstaged vs git_diff_staged vs git_diff)
  • memory server (9 tools): Add "Use when" triggers and clarify entity vs relation vs observation operations

No code changes -- only description strings updated.

Motivation

We built TeeShield, a scanner that rates MCP tool description quality. Scanning the official servers found:

Server Before After Change
git 2.9/10 8.7/10 +5.8
memory 3.4/10 9.6/10 +6.2

Key findings across 79 tools in 7 servers:

  • 0% of tools have scenario triggers ("Use when...")
  • 0% have parameter examples
  • Average description quality: 3.1/10

Test plan

  • Descriptions are factually accurate for each tool
  • No code logic changes, only string updates
  • Each description stays under 200 characters

🤖 Generated with Claude Code

Add scenario triggers ("Use when...") and disambiguation guidance to
tool descriptions in git and memory servers.

AI agents select tools based on description text. Current descriptions
are minimal (e.g., "Shows the working tree status") and give agents
no guidance on when to use each tool vs similar alternatives.

Changes:
- git: Add "Use when" guidance and disambiguation between diff tools
- memory: Add "Use when" guidance and clarify entity vs relation vs
  observation operations

No code changes -- only description strings updated.

Tested with TeeShield (https://github.com/teehooai/teeshield):
- git: description score 2.9 -> 8.7 (+5.8)
- memory: description score 3.4 -> 9.6 (+6.2)
@teehooai
Copy link
Author

teehooai commented Mar 9, 2026

Note: The CI failure in "Build fetch" is unrelated to this PR. The error is:

The lockfile at `uv.lock` needs to be updated, but `--locked` was provided.

This PR only modifies description strings in src/git/ and src/memory/ — no dependency or lockfile changes. The fetch package's uv.lock appears to be out of sync with its pyproject.toml on main.

@teehooai teehooai closed this by deleting the head repository Mar 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant