Skip to content

Improve MCP tool descriptions for ChatGPT compatibility #2937

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

Merged
merged 5 commits into from
Oct 31, 2025
Merged

Improve MCP tool descriptions for ChatGPT compatibility #2937

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4db6482
Initial plan
Copilot Oct 29, 2025
51333b9
Update MCP tool descriptions for better ChatGPT compatibility
Copilot Oct 29, 2025
a4871ef
Fix incorrect comment in DescribeEntitiesTool
Copilot Oct 29, 2025
96107e1
Expand describe_entities parameter descriptions for better clarity
Copilot Oct 29, 2025
9714542
Merge branch 'main' into copilot/improve-list-tools-descriptions
Aniruddh25 Oct 30, 2025
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
6 changes: 3 additions & 3 deletions src/Azure.DataApiBuilder.Mcp/BuiltInTools/CreateRecordTool.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,18 +31,18 @@ public Tool GetToolMetadata()
return new Tool
{
Name = "create_record",
Description = "Creates a new record in the specified entity.",
Description = "STEP 1: describe_entities -> find entities with CREATE permission and their fields. STEP 2: call this tool with matching field names and values.",
InputSchema = JsonSerializer.Deserialize<JsonElement>(
@"{
""type"": ""object"",
""properties"": {
""entity"": {
""type"": ""string"",
""description"": ""The name of the entity""
""description"": ""Entity name with CREATE permission.""
},
""data"": {
""type"": ""object"",
""description"": ""The data for the new record""
""description"": ""Required fields and values for the new record.""
}
},
""required"": [""entity"", ""data""]
Expand Down
6 changes: 3 additions & 3 deletions src/Azure.DataApiBuilder.Mcp/BuiltInTools/DeleteRecordTool.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,18 +44,18 @@ public Tool GetToolMetadata()
return new Tool
{
Name = "delete_record",
Description = "Deletes a record from a table based on primary key or composite key",
Description = "STEP 1: describe_entities -> find entities with DELETE permission and their key fields. STEP 2: call this tool with full key values.",
InputSchema = JsonSerializer.Deserialize<JsonElement>(
@"{
""type"": ""object"",
""properties"": {
""entity"": {
""type"": ""string"",
""description"": ""The name of the entity (table) as configured in dab-config. Required.""
""description"": ""Entity name with DELETE permission.""
},
""keys"": {
""type"": ""object"",
""description"": ""Primary key values to identify the record to delete. For composite keys, provide all key columns as properties. Required.""
""description"": ""All key fields identifying the record.""
}
},
""required"": [""entity"", ""keys""]
Expand Down
8 changes: 4 additions & 4 deletions src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,29 +25,29 @@ public class DescribeEntitiesTool : IMcpTool
public ToolType ToolType { get; } = ToolType.BuiltIn;

/// <summary>
/// Gets the metadata for the delete-record tool, including its name, description, and input schema.
/// Gets the metadata for the describe-entities tool, including its name, description, and input schema.
/// </summary>
/// <returns></returns>
public Tool GetToolMetadata()
{
return new Tool
{
Name = "describe_entities",
Description = "Lists and describes all entities in the database, including their types and available operations.",
Description = "Lists all entities and metadata. ALWAYS CALL FIRST. Each entity includes: name, type, fields, parameters, and permissions. The permissions array defines which tools are allowed. 'ALL' expands by type: data->CREATE, READ, UPDATE, DELETE.",
InputSchema = JsonSerializer.Deserialize<JsonElement>(
@"{
""type"": ""object"",
""properties"": {
""nameOnly"": {
""type"": ""boolean"",
""description"": ""If true, only entity names and descriptions will be returned. If false, full metadata including fields, parameters etc. will be included. Default is false.""
""description"": ""If true, the response includes only entity names and short summaries, omitting detailed metadata such as fields, parameters, and permissions. Use this when the database contains many entities and the full payload would be too large. The usual strategy is: first call describe_entities with nameOnly=true to get a lightweight list, then call describe_entities again with nameOnly=false for specific entities that require full metadata. This flag is meant for discovery, not execution planning. The model must not assume that nameOnly=true provides enough detail for CRUD or EXECUTE operations.""
},
""entities"": {
""type"": ""array"",
""items"": {
""type"": ""string""
},
""description"": ""Optional list of specific entity names to filter by. If empty, all entities will be described.""
""description"": ""Optional list of entity names to describe in full detail. Use this to reduce payload size when only certain entities are relevant. Do NOT pass both entities[] and nameOnly=true together, as that combination is nonsensical: nameOnly=true ignores detailed metadata, while entities[] explicitly requests it. Choose one approach—broad discovery with nameOnly=true OR targeted metadata with entities[].""
}
}
}"
Expand Down
6 changes: 3 additions & 3 deletions src/Azure.DataApiBuilder.Mcp/BuiltInTools/ExecuteEntityTool.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,18 +44,18 @@ public Tool GetToolMetadata()
return new Tool
{
Name = "execute_entity",
Description = "Executes a stored procedure or function, returns the results (if any)",
Description = "STEP 1: describe_entities -> find entities with EXECUTE permission and their parameters. STEP 2: call this tool with matching parameter values. Used for entities that perform actions or return computed results.",
InputSchema = JsonSerializer.Deserialize<JsonElement>(
@"{
""type"": ""object"",
""properties"": {
""entity"": {
""type"": ""string"",
""description"": ""The entity name of the procedure or function to execute. Must match a stored-procedure entity as configured in dab-config. Required.""
""description"": ""Entity name with EXECUTE permission.""
},
""parameters"": {
""type"": ""object"",
""description"": ""A dictionary of parameter names and values to pass to the procedure. Parameters must match those defined in dab-config. Optional if no parameters.""
""description"": ""Optional parameter names and values.""
}
},
""required"": [""entity""]
Expand Down
23 changes: 12 additions & 11 deletions src/Azure.DataApiBuilder.Mcp/BuiltInTools/ReadRecordsTool.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,37 +35,38 @@ public Tool GetToolMetadata()
return new Tool
{
Name = "read_records",
Description = "Retrieves records from a given entity.",
Description = "STEP 1: describe_entities -> find entities with READ permission and their fields. STEP 2: call this tool with select, filter, sort, or pagination options.",
InputSchema = JsonSerializer.Deserialize<JsonElement>(
@"{
""type"": ""object"",
""properties"": {
""entity"": {
""type"": ""string"",
""description"": ""The name of the entity to read, as provided by the describe_entities tool. Required.""
""description"": ""Entity name with READ permission.""
},
""select"": {
""type"": ""string"",
""description"": ""A comma-separated list of field names to include in the response. If omitted, all fields are returned. Optional.""
""description"": ""Comma-separated field names.""
},
""filter"": {
""type"": ""string"",
""description"": ""A case-insensitive OData-like expression that defines a query predicate. Supports logical grouping with parentheses and the operators eq, ne, gt, ge, lt, le, and, or, not. Examples: year ge 1990, date lt 2025-01-01T00:00:00Z, (title eq 'Foundation') and (available ne false). Optional.""
},
""first"": {
""type"": ""integer"",
""description"": ""The maximum number of records to return in the current page. Optional.""
""description"": ""OData expression: eq, ne, gt, ge, lt, le, and, or, not.""
},
""orderby"": {
""type"": ""array"",
""items"": { ""type"": ""string"" },
""description"": ""A list of field names and directions for sorting, for example 'name asc' or 'year desc'. Optional.""
""description"": ""Sort fields and directions, e.g., ['name asc', 'year desc'].""
},
""first"": {
""type"": ""integer"",
""description"": ""Max number of records (page size).""
},
""after"": {
""type"": ""string"",
""description"": ""A cursor token for retrieving the next page of results. Returned as 'after' in the previous response. Optional.""
""description"": ""Cursor token for next page.""
}
}
},
""required"": [""entity""]
}"
)
};
Expand Down
8 changes: 4 additions & 4 deletions src/Azure.DataApiBuilder.Mcp/BuiltInTools/UpdateRecordTool.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,22 +46,22 @@ public Tool GetToolMetadata()
return new Tool
{
Name = "update_record",
Description = "Updates an existing record in the specified entity. Requires 'keys' to locate the record and 'fields' to specify new values.",
Description = "STEP 1: describe_entities -> find entities with UPDATE permission and their key fields. STEP 2: call this tool with keys and new field values.",
InputSchema = JsonSerializer.Deserialize<JsonElement>(
@"{
""type"": ""object"",
""properties"": {
""entity"": {
""type"": ""string"",
""description"": ""The name of the entity""
""description"": ""Entity name with UPDATE permission.""
},
""keys"": {
""type"": ""object"",
""description"": ""Key fields and their values to identify the record""
""description"": ""Primary or composite keys identifying the record.""
},
""fields"": {
""type"": ""object"",
""description"": ""Fields and their new values to update""
""description"": ""Fields and their new values.""
}
},
""required"": [""entity"", ""keys"", ""fields""]
Expand Down
Loading