{
    "$schema": "https:\/\/json-schema.org\/draft\/2020-12\/schema",
    "$id": "https:\/\/www.totalcms.co\/schemas\/mcp-tool.json",
    "type": "object",
    "id": "mcp-tool",
    "description": "A saved-query tool exposed on the MCP server, defined per collection. Stored as a deck item \u2014 the deck key matches the tool's id.",
    "properties": {
        "id": {
            "$ref": "https:\/\/www.totalcms.co\/schemas\/properties\/slug.json",
            "label": "Tool ID",
            "help": "Snake_case identifier AI clients use to call this tool. Becomes the wire-level tool name when registered.",
            "field": "id",
            "factory": "slug",
            "pattern": "^[a-z][a-z0-9_]*$",
            "maxLength": 64,
            "settings": {
                "snakeCase": true
            }
        },
        "description": {
            "type": "string",
            "label": "Description",
            "help": "What this tool returns. Shown to AI agents in tools\/list \u2014 write for AI consumption, not LLM instructions.",
            "field": "textarea",
            "settings": {
                "rows": 2
            }
        },
        "params": {
            "type": "object",
            "label": "Params",
            "help": "Typed caller parameters as JSON. See <a href=\"docs\/mcp\/saved-query-tools\">the docs<\/a> for the param shape.",
            "field": "json",
            "placeholder": "{\n\t\"city\": {\n\t\t\"type\": \"string\",\n\t\t\"description\": \"City name.\",\n\t\t\"required\": true\n\t},\n\t\"max_price\": {\n\t\t\"type\": \"number\",\n\t\t\"minimum\": 0\n\t}\n}",
            "settings": {
                "rows": 6
            }
        },
        "filters": {
            "type": "object",
            "label": "Filters",
            "help": "Field-name \u2192 {value, operator} map as JSON. Filter values may reference <code>{{params.X}}<\/code> placeholders.",
            "field": "json",
            "placeholder": "{\n\t\"status\": { \"value\": \"active\" },\n\t\"city\":   { \"operator\": \"contains\", \"value\": \"{{params.city}}\" },\n\t\"price\":  { \"operator\": \"lte\",      \"value\": \"{{params.max_price}}\" }\n}",
            "settings": {
                "rows": 6
            }
        },
        "sort": {
            "type": "string",
            "label": "Sort",
            "help": "REST-style sort spec, e.g. <code>date:desc<\/code> or <code>priority:asc,date:desc<\/code>.",
            "field": "text",
            "placeholder": "date:desc"
        },
        "limit": {
            "type": "integer",
            "label": "Limit",
            "help": "Max results per call. Capped at 50.",
            "field": "number",
            "default": 20,
            "minimum": 1,
            "maximum": 50
        },
        "offset": {
            "type": "integer",
            "label": "Offset",
            "help": "Skip the first N matching results.",
            "field": "number",
            "default": 0,
            "minimum": 0
        },
        "include": {
            "type": "string",
            "label": "Include",
            "help": "REST-style include filter \u2014 escape hatch for shapes the structured filters object can't express.",
            "field": "text"
        },
        "exclude": {
            "type": "string",
            "label": "Exclude",
            "help": "REST-style exclude filter \u2014 escape hatch.",
            "field": "text"
        },
        "format": {
            "type": "string",
            "label": "Format",
            "help": "Output format for rich-text fields.",
            "field": "select",
            "default": "markdown",
            "options": [
                {
                    "value": "markdown",
                    "label": "Markdown"
                },
                {
                    "value": "html",
                    "label": "HTML"
                },
                {
                    "value": "text",
                    "label": "Plain text"
                }
            ]
        }
    },
    "required": [
        "id",
        "description"
    ],
    "index": [
        "id",
        "description"
    ],
    "formgrid": "id id\ndescription description\n---Query---\nparams params\nfilters filters\n---Result Shape---\nlimit offset\nformat format\nsort sort\ninclude include\nexclude exclude"
}