Skip to main content
Glama

Update custom report

update_report
Destructive

[Reports] Replace a custom report's definition (send the whole definition and the version from get_report). On a report shared with other people the change is saved as a draft that the owner publishes in the admin; a private report updates at once.

Replaces the definition of a report you own or may edit. Send the version you read; if someone changed the report since, you get 409 and should get it again. A report shared with others keeps your change as a draft until it is published in the admin, so viewers never see a half-finished report.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesReport id (from list_reports).
targetNopublished (default) or draft. A private report always publishes. Through the MCP server a shared report always gets a draft that its owner publishes in the admin.
versionYesThe version you read (get_report / list_reports). A stale version is refused with 409.
definitionYes
merchant_idNoOptional merchant to act on. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_idNoPass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYes
versionYesSend it back with the next update.
admin_urlYesOpen the report in the JobMojito admin.
publishedYesfalse when the change was stored as a draft the owner publishes in the admin.
_mcp_instructionsNoServer-issued metadata for this conversation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / definition / allOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "description": "A custom report: report-wide filters and up to 12 blocks. Read report-catalog first for the dataset, field and measure ids.",
      -    "example": {
      -      "blocks": [
      -        {
      -          "compare": "previous_period",
      -          "dataset": "interview_results",
      -          "id": "headline",
      -          "measures": [
      -            "completed",
      -            "avg_score",
      -            "shortlisted"
      -          ],
      -          "type": "kpi"
      -        },
      -        {
      -          "dataset": "interview_results",
      -          "dimensions": [
      -            {
      -              "field": "date",
      -              "grain": "week"
      -            }
      -          ],
      -          "id": "trend",
      -          "measures": [
      -            "completed"
      -          ],
      -          "title": "Completed per week",
      -          "type": "line",
      -          "width": 8
      -        },
      -        {
      -          "dataset": "interview_results",
      -          "dimensions": [
      -            "position"
      -          ],
      -          "id": "by_position",
      -          "limit": 25,
      -          "measures": [
      -            "completed",
      -            "avg_score",
      -            "shortlisted"
      -          ],
      -          "sort": [
      -            {
      -              "dir": "desc",
      -              "field": "completed"
      -            }
      -          ],
      -          "title": "By position",
      -          "type": "table"
      -        }
      -      ],
      -      "filters": {
      -        "period": {
      -          "preset": "last_30_days"
      -        }
      -      },
      -      "schema": "jobmojito.report/v1",
      -      "title": "Weekly hiring pulse"
      -    },
      -    "properties": {
      -      "blocks": {
      -        "items": {
      -          "additionalProperties": false,
      -          "properties": {
      -            "compare": {
      -              "description": "kpi / funnel only: also return the same numbers for the period before.",
      -              "enum": [
      -                "previous_period",
      -                null
      -              ],
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "dataset": {
      -              "description": "Dataset id from report-catalog. Not used by a text block.",
      -              "example": "interview_results",
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "dimensions": {
      -              "items": {
      -                "anyOf": [
      -                  {
      -                    "pattern": "^[a-z][a-z0-9_]{0,40}$",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "additionalProperties": false,
      -                    "properties": {
      -                      "field": {
      -                        "pattern": "^[a-z][a-z0-9_]{0,40}$",
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      },
      -                      "grain": {
      -                        "description": "For a date field: day (default), week, month, quarter or year.",
      -                        "enum": [
      -                          "day",
      -                          "week",
      -                          "month",
      -                          "quarter",
      -                          "year",
      -                          null
      -                        ],
      -                        "type": [
      -                          "string",
      -                          "null"
      -                        ]
      -                      }
      -                    },
      -                    "required": [
      -                      "field"
      -                    ],
      -                    "type": "object"
      -                  }
      -                ],
      -                "description": "A dimension field id, or {\"field\", \"grain\"} for a date."
      -              },
      -              "maxItems": 2,
      -              "type": [
      -                "array",
      -                "null"
      -              ]
      -            },
      -            "id": {
      -              "example": "by_position",
      -              "pattern": "^[A-Za-z0-9_-]{1,40}$",
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "limit": {
      -              "description": "Rows for a table / bar / line. Default 100 (line 500).",
      -              "maximum": 500,
      -              "minimum": 1,
      -              "type": [
      -                "integer",
      -                "null"
      -              ]
      -            },
      -            "measures": {
      -              "description": "1 to 6 measure ids of the dataset.",
      -              "example": [
      -                "completed",
      -                "avg_score"
      -              ],
      -              "items": {
      -                "pattern": "^[a-z][a-z0-9_]{0,40}$",
      -                "type": "string"
      -              },
      -              "maxItems": 6,
      -              "minItems": 1,
      -              "type": [
      -                "array",
      -                "null"
      -              ]
      -            },
      -            "sort": {
      -              "items": {
      -                "additionalProperties": false,
      -                "properties": {
      -                  "dir": {
      -                    "enum": [
      -                      "asc",
      -                      "desc",
      -                      null
      -                    ],
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "field": {
      -                    "description": "A dimension or measure the block selects.",
      -                    "pattern": "^[a-z][a-z0-9_]{0,40}$",
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  }
      -                },
      -                "required": [
      -                  "field"
      -                ],
      -                "type": "object"
      -              },
      -              "maxItems": 3,
      -              "type": [
      -                "array",
      -                "null"
      -              ]
      -            },
      -            "text": {
      -              "description": "Text block only: the note (plain text, line breaks kept).",
      -              "maxLength": 4000,
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "title": {
      -              "maxLength": 120,
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "type": {
      -              "description": "kpi: one total per measure (no dimensions; add compare previous_period for a change). funnel: 2+ measures as steps (no dimensions). table: 0-2 dimensions. bar: 1-2 dimensions. stacked_bar: exactly 2 dimensions. line: first dimension a date. text: a note, only `text`.",
      -              "enum": [
      -                "kpi",
      -                "table",
      -                "bar",
      -                "stacked_bar",
      -                "line",
      -                "funnel",
      -                "text",
      -                null
      -              ],
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "where": {
      -              "items": {
      -                "additionalProperties": false,
      -                "properties": {
      -                  "field": {
      -                    "description": "A dimension of the block's dataset.",
      -                    "pattern": "^[a-z][a-z0-9_]{0,40}$",
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "op": {
      -                    "enum": [
      -                      "eq",
      -                      "neq",
      -                      "in",
      -                      "not_in",
      -                      "gt",
      -                      "gte",
      -                      "lt",
      -                      "lte",
      -                      "between",
      -                      "is_empty",
      -                      "is_not_empty",
      -                      null
      -                    ],
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "value": {
      -                    "anyOf": [
      -                      {
      -                        "type": "string"
      -                      },
      -                      {
      -                        "type": "number"
      -                      },
      -                      {
      -                        "type": "boolean"
      -                      },
      -                      {
      -                        "items": {
      -                          "anyOf": [
      -                            {
      -                              "type": "string"
      -                            },
      -                            {
      -                              "type": "number"
      -                            }
      -                          ]
      -                        },
      -                        "type": "array"
      -                      }
      -                    ],
      -                    "description": "One value for eq / neq / gt / gte / lt / lte, a list for in / not_in, [low, high] for between, nothing for is_empty / is_not_empty."
      -                  }
      -                },
      -                "required": [
      -                  "field",
      -                  "op"
      -                ],
      -                "type": "object"
      -              },
      -              "maxItems": 10,
      -              "type": [
      -                "array",
      -                "null"
      -              ]
      -            },
      -            "width": {
      -              "description": "Columns of a 12-column grid. Default 12.",
      -              "maximum": 12,
      -              "minimum": 1,
      -              "type": [
      -                "integer",
      -                "null"
      -              ]
      -            }
      -          },
      -          "required": [
      -            "id",
      -            "type"
      -          ],
      -          "type": "object"
      -        },
      -        "maxItems": 12,
      -        "type": [
      -          "array",
      -          "null"
      -        ]
      -      },
      -      "description": {
      -        "maxLength": 1000,
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "filters": {
      -        "additionalProperties": false,
      -        "description": "Filters for every block of the report. Each viewer can override them for themselves.",
      -        "properties": {
      -          "include_test": {
      -            "description": "Include test runs. Default false.",
      -            "type": [
      -              "boolean",
      -              "null"
      -            ]
      -          },
      -          "interview_ids": {
      -            "description": "Only these interviews (interview ids from list_interviews). Empty or missing = all.",
      -            "items": {
      -              "format": "uuid",
      -              "type": "string"
      -            },
      -            "maxItems": 200,
      -            "type": [
      -              "array",
      -              "null"
      -            ]
      -          },
      -          "period": {
      -            "anyOf": [
      -              {
      -                "additionalProperties": false,
      -                "properties": {
      -                  "preset": {
      -                    "enum": [
      -                      "last_7_days",
      -                      "last_30_days",
      -                      "last_90_days",
      -                      "this_month",
      -                      "last_month",
      -                      "this_quarter",
      -                      "last_quarter",
      -                      "this_year",
      -                      "last_year",
      -                      "all_time",
      -                      null
      -                    ],
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  }
      -                },
      -                "required": [
      -                  "preset"
      -                ],
      -                "type": "object"
      -              },
      -              {
      -                "additionalProperties": false,
      -                "properties": {
      -                  "from": {
      -                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  },
      -                  "to": {
      -                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                    "type": [
      -                      "string",
      -                      "null"
      -                    ]
      -                  }
      -                },
      -                "required": [
      -                  "from",
      -                  "to"
      -                ],
      -                "type": "object"
      -              }
      -            ],
      -            "description": "Either a preset, or from and to dates (YYYY-MM-DD, both inclusive, UTC). Default: last_30_days.",
      -            "example": {
      -              "preset": "last_30_days"
      -            }
      -          },
      -          "position_ids": {
      -            "description": "Only these positions (position ids from list_interviews). Empty or missing = all.",
      -            "items": {
      -              "format": "uuid",
      -              "type": "string"
      -            },
      -            "maxItems": 200,
      -            "type": [
      -              "array",
      -              "null"
      -            ]
      -          }
      -        },
      -        "type": "object"
      -      },
      -      "schema": {
      -        "description": "Always \"jobmojito.report/v1\".",
      -        "enum": [
      -          "jobmojito.report/v1",
      -          null
      -        ],
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "title": {
      -        "maxLength": 120,
      -        "minLength": 1,
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      }
      -    },
      -    "required": [
      -      "schema",
      -      "title",
      -      "blocks"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "description": "The whole new definition (it replaces the old one)."
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "description": "A custom report: report-wide filters and up to 12 blocks. Read report-catalog first for the dataset, field and measure ids.",
      +    "example": {
      +      "blocks": [
      +        {
      +          "compare": "previous_period",
      +          "dataset": "interview_results",
      +          "id": "headline",
      +          "measures": [
      +            "completed",
      +            "avg_score",
      +            "shortlisted"
      +          ],
      +          "type": "kpi"
      +        },
      +        {
      +          "dataset": "interview_results",
      +          "dimensions": [
      +            {
      +              "field": "date",
      +              "grain": "week"
      +            }
      +          ],
      +          "id": "trend",
      +          "measures": [
      +            "completed"
      +          ],
      +          "title": "Completed per week",
      +          "type": "line",
      +          "width": 8
      +        },
      +        {
      +          "dataset": "interview_results",
      +          "dimensions": [
      +            "position"
      +          ],
      +          "id": "by_position",
      +          "limit": 25,
      +          "measures": [
      +            "completed",
      +            "avg_score",
      +            "shortlisted"
      +          ],
      +          "sort": [
      +            {
      +              "dir": "desc",
      +              "field": "completed"
      +            }
      +          ],
      +          "title": "By position",
      +          "type": "table"
      +        }
      +      ],
      +      "filters": {
      +        "period": {
      +          "preset": "last_30_days"
      +        }
      +      },
      +      "schema": "jobmojito.report/v1",
      +      "title": "Weekly hiring pulse"
      +    },
      +    "properties": {
      +      "blocks": {
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "compare": {
      +              "description": "kpi / funnel only: also return the same numbers for the period before.",
      +              "enum": [
      +                "previous_period",
      +                null
      +              ],
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "dataset": {
      +              "description": "Dataset id from report-catalog. Not used by a text block.",
      +              "example": "interview_results",
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "dimensions": {
      +              "items": {
      +                "anyOf": [
      +                  {
      +                    "pattern": "^[a-z][a-z0-9_]{0,40}$",
      +                    "type": "string"
      +                  },
      +                  {
      +                    "additionalProperties": false,
      +                    "properties": {
      +                      "field": {
      +                        "pattern": "^[a-z][a-z0-9_]{0,40}$",
      +                        "type": [
      +                          "string",
      +                          "null"
      +                        ]
      +                      },
      +                      "grain": {
      +                        "description": "For a date field: day (default), week, month, quarter or year.",
      +                        "enum": [
      +                          "day",
      +                          "week",
      +                          "month",
      +                          "quarter",
      +                          "year",
      +                          null
      +                        ],
      +                        "type": [
      +                          "string",
      +                          "null"
      +                        ]
      +                      }
      +                    },
      +                    "required": [
      +                      "field"
      +                    ],
      +                    "type": "object"
      +                  }
      +                ],
      +                "description": "A dimension field id, or {\"field\", \"grain\"} for a date."
      +              },
      +              "maxItems": 2,
      +              "type": [
      +                "array",
      +                "null"
      +              ]
      +            },
      +            "id": {
      +              "example": "by_position",
      +              "pattern": "^[A-Za-z0-9_-]{1,40}$",
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "limit": {
      +              "description": "Rows for a table / bar / line. Default 100 (line 500).",
      +              "maximum": 500,
      +              "minimum": 1,
      +              "type": [
      +                "integer",
      +                "null"
      +              ]
      +            },
      +            "measures": {
      +              "description": "1 to 6 measure ids of the dataset.",
      +              "example": [
      +                "completed",
      +                "avg_score"
      +              ],
      +              "items": {
      +                "pattern": "^[a-z][a-z0-9_]{0,40}$",
      +                "type": "string"
      +              },
      +              "maxItems": 6,
      +              "minItems": 1,
      +              "type": [
      +                "array",
      +                "null"
      +              ]
      +            },
      +            "sort": {
      +              "items": {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "dir": {
      +                    "enum": [
      +                      "asc",
      +                      "desc",
      +                      null
      +                    ],
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "field": {
      +                    "description": "A dimension or measure the block selects.",
      +                    "pattern": "^[a-z][a-z0-9_]{0,40}$",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                },
      +                "required": [
      +                  "field"
      +                ],
      +                "type": "object"
      +              },
      +              "maxItems": 3,
      +              "type": [
      +                "array",
      +                "null"
      +              ]
      +            },
      +            "text": {
      +              "description": "Text block only: the note (plain text, line breaks kept).",
      +              "maxLength": 4000,
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "title": {
      +              "maxLength": 120,
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "type": {
      +              "description": "kpi: one total per measure (no dimensions; add compare previous_period for a change). funnel: 2+ measures as steps (no dimensions). table: 0-2 dimensions. bar: 1-2 dimensions. stacked_bar: exactly 2 dimensions. line: first dimension a date. text: a note, only `text`.",
      +              "enum": [
      +                "kpi",
      +                "table",
      +                "bar",
      +                "stacked_bar",
      +                "line",
      +                "funnel",
      +                "text",
      +                null
      +              ],
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "where": {
      +              "items": {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "field": {
      +                    "description": "A dimension of the block's dataset.",
      +                    "pattern": "^[a-z][a-z0-9_]{0,40}$",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "op": {
      +                    "enum": [
      +                      "eq",
      +                      "neq",
      +                      "in",
      +                      "not_in",
      +                      "gt",
      +                      "gte",
      +                      "lt",
      +                      "lte",
      +                      "between",
      +                      "is_empty",
      +                      "is_not_empty",
      +                      null
      +                    ],
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "value": {
      +                    "anyOf": [
      +                      {
      +                        "type": "string"
      +                      },
      +                      {
      +                        "type": "number"
      +                      },
      +                      {
      +                        "type": "boolean"
      +                      },
      +                      {
      +                        "items": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "number"
      +                            }
      +                          ]
      +                        },
      +                        "type": "array"
      +                      }
      +                    ],
      +                    "description": "One value for eq / neq / gt / gte / lt / lte, a list for in / not_in, [low, high] for between, nothing for is_empty / is_not_empty."
      +                  }
      +                },
      +                "required": [
      +                  "field",
      +                  "op"
      +                ],
      +                "type": "object"
      +              },
      +              "maxItems": 10,
      +              "type": [
      +                "array",
      +                "null"
      +              ]
      +            },
      +            "width": {
      +              "description": "Columns of a 12-column grid. Default 12.",
      +              "maximum": 12,
      +              "minimum": 1,
      +              "type": [
      +                "integer",
      +                "null"
      +              ]
      +            }
      +          },
      +          "required": [
      +            "id",
      +            "type"
      +          ],
      +          "type": "object"
      +        },
      +        "maxItems": 12,
      +        "type": [
      +          "array",
      +          "null"
      +        ]
      +      },
      +      "description": {
      +        "maxLength": 1000,
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "filters": {
      +        "additionalProperties": false,
      +        "description": "Filters for every block of the report. Each viewer can override them for themselves.",
      +        "properties": {
      +          "include_test": {
      +            "description": "Include test runs. Default false.",
      +            "type": [
      +              "boolean",
      +              "null"
      +            ]
      +          },
      +          "interview_ids": {
      +            "description": "Interviews to show (interview ids from list_interviews), combined with the other picks by OR. Nothing picked = all.",
      +            "items": {
      +              "format": "uuid",
      +              "type": "string"
      +            },
      +            "maxItems": 200,
      +            "type": [
      +              "array",
      +              "null"
      +            ]
      +          },
      +          "period": {
      +            "anyOf": [
      +              {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "preset": {
      +                    "enum": [
      +                      "last_7_days",
      +                      "last_30_days",
      +                      "last_90_days",
      +                      "this_month",
      +                      "last_month",
      +                      "this_quarter",
      +                      "last_quarter",
      +                      "this_year",
      +                      "last_year",
      +                      "all_time",
      +                      null
      +                    ],
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                },
      +                "required": [
      +                  "preset"
      +                ],
      +                "type": "object"
      +              },
      +              {
      +                "additionalProperties": false,
      +                "properties": {
      +                  "from": {
      +                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  },
      +                  "to": {
      +                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      +                    "type": [
      +                      "string",
      +                      "null"
      +                    ]
      +                  }
      +                },
      +                "required": [
      +                  "from",
      +                  "to"
      +                ],
      +                "type": "object"
      +              }
      +            ],
      +            "description": "Either a preset, or from and to dates (YYYY-MM-DD, both inclusive, UTC). Default: last_30_days.",
      +            "example": {
      +              "preset": "last_30_days"
      +            }
      +          },
      +          "position_ids": {
      +            "description": "Positions to show (position ids from list_interviews). position_ids, interview_ids and without_position are one pick list: a row shows when it belongs to ANY pick. Nothing picked = all.",
      +            "items": {
      +              "format": "uuid",
      +              "type": "string"
      +            },
      +            "maxItems": 200,
      +            "type": [
      +              "array",
      +              "null"
      +            ]
      +          },
      +          "without_position": {
      +            "description": "Also pick interviews that are not part of any position (stand-alone interviews, and coaching sessions). Combined with the other picks by OR.",
      +            "type": [
      +              "boolean",
      +              "null"
      +            ]
      +          }
      +        },
      +        "type": "object"
      +      },
      +      "schema": {
      +        "description": "Always \"jobmojito.report/v1\".",
      +        "enum": [
      +          "jobmojito.report/v1",
      +          null
      +        ],
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "title": {
      +        "maxLength": 120,
      +        "minLength": 1,
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "schema",
      +      "title",
      +      "blocks"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "description": "The whole new definition (it replaces the old one)."
      +  }
      +]
  2. Added

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description adds genuinely non-derivable behavior: shared reports persist the change as a draft until admin publication while private reports update immediately, and stale versions are rejected with 409. It does not discuss auth/permission specifics beyond ownership.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loading is good ([Reports] tag and the replace action lead), but the second paragraph largely repeats the first: full replacement, version/409 handling, and the shared-report draft behavior appear twice. Roughly a third of the text is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and annotations cover the destructive/idempotency profile. The description supplies the ownership scope, conflict handling, and draft-vs-publish semantics an agent needs to call this correctly; only explicit permission/authorization detail is thin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents id, version, target, definition, merchant_id and conversation_id in detail. The description restates "send the whole definition and the version from get_report" but adds no syntax, format, or constraint beyond what the schema already says, including the 409-on-stale-version rule.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource: "Replace a custom report's definition," and immediately clarifies it is a full replacement ("send the whole definition"), not a partial patch. It names the sibling get_report as the source of the input, so an agent can distinguish it from create_report, preview_report, and run_report without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear preconditions ("a report you own or may edit") and the exact call sequence: read via get_report, then resend the version. It also explains the conflict path (stale version → 409 → re-read). It stops short of explicit when-not guidance, e.g. pointing to create_report for new reports or preview_report for validation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.