Improve MCP tool descriptions for ChatGPT compatibility

[Copilot]

MCP list_tools descriptions were insufficiently clear for ChatGPT to understand tool usage patterns and workflows, while Claude handled them adequately.

Changes

Updated descriptions and input schemas for all 6 MCP tools:

• describe_entities: Added "ALWAYS CALL FIRST" directive and clarified permissions structure ('ALL' expands by type: data→CREATE, READ, UPDATE, DELETE). Expanded nameOnly and entities parameter descriptions to include detailed usage guidance:
  • nameOnly: Explains when to use it (for discovery with many entities), the two-call strategy (first with nameOnly=true, then with specific entities), and warns that it doesn't provide enough detail for CRUD/EXECUTE operations
  • entities: Clarifies its purpose for targeted metadata retrieval and explicitly warns against combining it with nameOnly=true
• CRUD tools (create_record, read_records, update_record, delete_record): Added explicit STEP 1→STEP 2 workflow (describe_entities first, then call with matching permissions/fields)
• execute_entity: Added workflow guidance and clarified use case (actions/computed results)
• All tools: Condensed parameter descriptions (e.g., "Comma-separated field names" vs. "A comma-separated list of field names to include in the response. If omitted, all fields are returned. Optional.")

Example

Before:

Description = "Creates a new record in the specified entity."

After:

Description = "STEP 1: describe_entities -> find entities with CREATE permission and their fields. STEP 2: call this tool with matching field names and values."

All changes are metadata-only; no functional code modified.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[BUG]: MCP list_tools need more comprehensive descriptions.</issue_title>
<issue_description>## What?

Our tools have descriptions already. They need better to help models.

Claude works but ChatGPT struggles to understand with our current descriptions.

New descriptions

{
  "tools": [
    {
      "name": "describe_entities",
      "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": {
        "type": "object",
        "properties": {
          "nameOnly": {
            "type": "boolean",
            "description": "True: names and summaries only. False (default): full metadata."
          },
          "entities": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Optional: specific entity names. Omit for all."
          }
        }
      }
    },
    {
      "name": "create_record",
      "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": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Entity name with CREATE permission."
          },
          "data": {
            "type": "object",
            "description": "Required fields and values for the new record."
          }
        },
        "required": ["entity", "data"]
      }
    },
    {
      "name": "read_records",
      "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": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Entity name with READ permission."
          },
          "select": {
            "type": "string",
            "description": "Comma-separated field names."
          },
          "filter": {
            "type": "string",
            "description": "OData expression: eq, ne, gt, ge, lt, le, and, or, not."
          },
          "orderby": {
            "type": "array",
            "items": { "type": "string" },
            "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": "Cursor token for next page."
          }
        },
        "required": ["entity"]
      }
    },
    {
      "name": "update_record",
      "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": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Entity name with UPDATE permission."
          },
          "keys": {
            "type": "object",
            "description": "Primary or composite keys identifying the record."
          },
          "fields": {
            "type": "object",
            "description": "Fields and their new values."
          }
        },
        "required": ["entity", "keys", "fields"]
      }
    },
    {
      "name": "delete_record",
      "description": "STEP 1: describe_entities -> find entities with DELETE permission and their key fields. STEP 2: call this tool with full key values.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Entity name with DELETE permission."
          },
          "keys": {
            "type": "object",
            "description": "All key fields identifying the record."
          }
        },
        "required": ["entity", "keys"]
      }
    },
    {
      "name": "execute_entity",
      "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": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Entity name with EXECUTE permission."
          },
          "parameters": {
            "type": "object",
            "description": "Optional parameter names and values."
          }
        },
        "required": ["entity"]
      }
    }
  ]
}

</issue_description>

<agent_instruction...

• Fixes [BUG]: MCP list_tools need more comprehensive descriptions. #2936

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[JerryNixon]

@copilot Can we make describe even more clear?

{
  "name": "describe_entities",
  "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": {
    "type": "object",
    "properties": {
      "nameOnly": {
        "type": "boolean",
        "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 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[]."
      }
    }
  }
}

[Copilot]

@copilot Can we make describe even more clear?

...

Updated the describe_entities parameter descriptions with the more comprehensive explanations in commit 96107e1.

The nameOnly description now includes:

• When to use it (for discovery with many entities)
• The two-call strategy (first with nameOnly=true, then with specific entities)
• Warning that it's not sufficient for CRUD/EXECUTE operations

The entities description now includes:

• Guidance on reducing payload size
• Explicit warning not to combine with nameOnly=true
• Clear choice between broad discovery vs targeted metadata approaches

[JerryNixon]

This is just as requested.

[Copilot]

Pull Request Overview

This pull request enhances the tool descriptions and parameter documentation across all built-in MCP tools to provide clearer guidance for AI agents. The changes emphasize a two-step workflow pattern and make parameter descriptions more concise.

• Introduced consistent "STEP 1: describe_entities → STEP 2: call this tool" workflow across CRUD and execute operations
• Simplified and clarified parameter descriptions to be more concise while maintaining necessary information
• Added explicit permission requirements to entity descriptions and corrected a comment typo in DescribeEntitiesTool

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
UpdateRecordTool.cs	Updated tool and parameter descriptions to emphasize two-step workflow and clarify UPDATE permission requirement
ReadRecordsTool.cs	Streamlined descriptions, added two-step workflow pattern, moved first parameter position, and added required fields
ExecuteEntityTool.cs	Enhanced description with two-step workflow and clarified EXECUTE permission context
DescribeEntitiesTool.cs	Fixed comment typo, expanded main description with permission details, and significantly enhanced nameOnly and entities parameter documentation
DeleteRecordTool.cs	Updated to follow two-step workflow pattern and simplified parameter descriptions
CreateRecordTool.cs	Added two-step workflow guidance and clarified CREATE permission requirements

Comments suppressed due to low confidence (2)

src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs:1

• This description is excessively long for a JSON schema field description (over 500 characters). Consider condensing it to focus on the essential behavior: what the flag does and when to use it. The detailed usage strategy and warnings could be documented in code comments or external documentation instead.

// Copyright (c) Microsoft Corporation.

src/Azure.DataApiBuilder.Mcp/BuiltInTools/DescribeEntitiesTool.cs:1

• This description is overly verbose (over 400 characters) and contains prescriptive guidance about parameter combinations that would be better enforced through input validation or documented elsewhere. Consider simplifying to: 'Optional list of specific entity names to describe in detail. Filters the response to only the specified entities.'

// Copyright (c) Microsoft Corporation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Aniruddh25]

/azp run

[Aniruddh25]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 6 pipeline(s).

[aaronburtle]

Looks good!