Skip to content

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

@JerryNixon

Description

@JerryNixon

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"]
      }
    }
  ]
}

Metadata

Metadata

Type

Projects

Status

Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions