Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
teehooai wants to merge 1 commit into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 12 additions & 14 deletions src/git/src/mcp_server_git/server.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,65 +287,63 @@ async def list_tools() -> list[Tool]:
return [
Tool(
name=GitTools.STATUS,
description="Shows the working tree status",
description="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.",
inputSchema=GitStatus.model_json_schema(),
),
Tool(
name=GitTools.DIFF_UNSTAGED,
description="Shows changes in the working directory that are not yet staged",
description="Show changes in working directory files that are not yet staged. Use when the user wants to review modifications before running git_add. Unlike git_diff_staged, this shows only unstaged changes.",
inputSchema=GitDiffUnstaged.model_json_schema(),
),
Tool(
name=GitTools.DIFF_STAGED,
description="Shows changes that are staged for commit",
description="Show changes that are staged for the next commit. Use when the user wants to review exactly what will be committed. Unlike git_diff_unstaged, this shows only staged changes.",
inputSchema=GitDiffStaged.model_json_schema(),
),
Tool(
name=GitTools.DIFF,
description="Shows differences between branches or commits",
description="Show differences between two branches, commits, or tags. Use when the user wants to compare code across branches or review changes between specific commits.",
inputSchema=GitDiff.model_json_schema(),
),
Tool(
name=GitTools.COMMIT,
description="Records changes to the repository",
description="Record staged changes to the repository with a message. Use when the user wants to save their staged changes as a new commit. Requires files to be staged first with git_add.",
inputSchema=GitCommit.model_json_schema(),
),
Tool(
name=GitTools.ADD,
description="Adds file contents to the staging area",
description="Stage file changes for the next commit. Use when the user wants to prepare specific files for committing. Use git_status first to see which files have changes.",
inputSchema=GitAdd.model_json_schema(),
),
Tool(
name=GitTools.RESET,
description="Unstages all staged changes",
description="Unstage all staged changes, moving them back to the working directory. Use when the user wants to undo git_add without losing the actual file changes.",
inputSchema=GitReset.model_json_schema(),
),
Tool(
name=GitTools.LOG,
description="Shows the commit logs",
description="Show the commit history log. Use when the user wants to review past commits, find a specific change, or see who changed what and when.",
inputSchema=GitLog.model_json_schema(),
),
Tool(
name=GitTools.CREATE_BRANCH,
description="Creates a new branch from an optional base branch",
description="Create a new branch from an optional base branch. Use when the user wants to start working on a new feature or fix without affecting the current branch.",
inputSchema=GitCreateBranch.model_json_schema(),
),
Tool(
name=GitTools.CHECKOUT,
description="Switches branches",
description="Switch to a different branch. Use when the user wants to change their working context to an existing branch. Use git_create_branch first if the branch does not exist.",
inputSchema=GitCheckout.model_json_schema(),
),
Tool(
name=GitTools.SHOW,
description="Shows the contents of a commit",
description="Show the contents and metadata of a specific commit. Use when the user wants to inspect what changed in a particular commit, including the diff and commit message.",
inputSchema=GitShow.model_json_schema(),
),

Tool(
name=GitTools.BRANCH,
description="List Git branches",
description="List all local and remote branches. Use when the user wants to see available branches before switching or to check if a branch exists.",
inputSchema=GitBranch.model_json_schema(),

)
]

Expand Down
18 changes: 9 additions & 9 deletions src/memory/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ server.registerTool(
"create_entities",
{
title: "Create Entities",
description: "Create multiple new entities in the knowledge graph",
description: "Create multiple new entities in the knowledge graph. Use when the user wants to add new concepts, people, or objects. Each entity needs a name, type, and optional observations.",
inputSchema: {
entities: z.array(EntitySchema)
},
Expand All @@ -285,7 +285,7 @@ server.registerTool(
"create_relations",
{
title: "Create Relations",
description: "Create multiple new relations between entities in the knowledge graph. Relations should be in active voice",
description: "Create multiple new relations between entities in the knowledge graph. Relations must use active voice (e.g., 'works_at' not 'is_employed_by'). Use when the user wants to connect existing entities.",
inputSchema: {
relations: z.array(RelationSchema)
},
Expand All @@ -307,7 +307,7 @@ server.registerTool(
"add_observations",
{
title: "Add Observations",
description: "Add new observations to existing entities in the knowledge graph",
description: "Add new observations to existing entities in the knowledge graph. Use when the user wants to record new facts about an entity without creating duplicates. Unlike create_entities, this updates existing entries.",
inputSchema: {
observations: z.array(z.object({
entityName: z.string().describe("The name of the entity to add the observations to"),
Expand Down Expand Up @@ -335,7 +335,7 @@ server.registerTool(
"delete_entities",
{
title: "Delete Entities",
description: "Delete multiple entities and their associated relations from the knowledge graph",
description: "Delete multiple entities and all their associated relations from the knowledge graph. Use when the user wants to permanently remove concepts. This also removes all relations involving the deleted entities.",
inputSchema: {
entityNames: z.array(z.string()).describe("An array of entity names to delete")
},
Expand All @@ -358,7 +358,7 @@ server.registerTool(
"delete_observations",
{
title: "Delete Observations",
description: "Delete specific observations from entities in the knowledge graph",
description: "Delete specific observations from entities in the knowledge graph. Use when the user wants to remove outdated or incorrect facts from an entity without deleting the entity itself.",
inputSchema: {
deletions: z.array(z.object({
entityName: z.string().describe("The name of the entity containing the observations"),
Expand All @@ -384,7 +384,7 @@ server.registerTool(
"delete_relations",
{
title: "Delete Relations",
description: "Delete multiple relations from the knowledge graph",
description: "Delete multiple relations from the knowledge graph. Use when the user wants to remove connections between entities without deleting the entities themselves.",
inputSchema: {
relations: z.array(RelationSchema).describe("An array of relations to delete")
},
Expand All @@ -407,7 +407,7 @@ server.registerTool(
"read_graph",
{
title: "Read Graph",
description: "Read the entire knowledge graph",
description: "Read the entire knowledge graph including all entities and relations. Use when the user wants a complete overview. For large graphs, prefer search_nodes to find specific items.",
inputSchema: {},
outputSchema: {
entities: z.array(EntitySchema),
Expand All @@ -428,7 +428,7 @@ server.registerTool(
"search_nodes",
{
title: "Search Nodes",
description: "Search for nodes in the knowledge graph based on a query",
description: "Search for nodes in the knowledge graph by matching against entity names, types, and observations. Use when the user wants to find specific entities without loading the entire graph.",
inputSchema: {
query: z.string().describe("The search query to match against entity names, types, and observation content")
},
Expand All @@ -451,7 +451,7 @@ server.registerTool(
"open_nodes",
{
title: "Open Nodes",
description: "Open specific nodes in the knowledge graph by their names",
description: "Retrieve specific nodes from the knowledge graph by their exact names. Use when the user wants to look up known entities directly. Unlike search_nodes, this requires exact name matches.",
inputSchema: {
names: z.array(z.string()).describe("An array of entity names to retrieve")
},
Expand Down
Loading