Cleotic

Get opportunity

get_opportunity

Read-onlyIdempotent

One opportunity with its evidence (who is winning, verbatim excerpts, cited sources, trend), its play and the tool call that carries it out, before/after proof, timeline, and comments. Content gaps include each engine's latest answer. Read it before act_on_opportunity or create_page; to browse the inbox use list_opportunities.

Input Schema

Name	Required	Description	Default
`brand`	Yes	Brand or study: its ID from list_brands, or its name (exact or a unique prefix).
`opportunity_id`	Yes	Opportunity ID from list_opportunities.

Output Schema

Name	Required	Description
`data`	Yes
`generated_at`	Yes	RFC 3339 time the response was made.
`schema_version`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedOct 13, 2026

removedOutput schema / properties / data / properties / play / properties / page_ideas

Removed value: -{
-  "items": {
-    "additionalProperties": false,
-    "properties": {
-      "content_type": {
-        "type": "string"
-      },
-      "covered": {
-        "description": "An existing page already covers it.",
-        "type": "boolean"
-      },
-      "objective": {
-        "type": "string"
-      },
-      "title": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "title",
-      "content_type",
-      "objective",
-      "covered"
-    ],
-    "type": "object"
-  },
-  "type": "array"
-}

addedOutput schema / properties / data / properties / play / properties / page_results

Added value: +{
+  "additionalProperties": false,
+  "description": "draft_content: results of its most recently live page.",
+  "properties": {
+    "crawlers": {
+      "description": "AI crawlers that have read the page since it went live.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "crawler": {
+            "type": "string"
+          },
+          "first_at": {
+            "type": "string"
+          },
+          "reads": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "crawler",
+          "first_at",
+          "reads"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "targets": {
+      "description": "For each target question: answers in the 4 weeks before it went live and since.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "before": {
+            "additionalProperties": false,
+            "properties": {
+              "answers": {
+                "type": "integer"
+              },
+              "cited": {
+                "description": "Answers that cite the page.",
+                "type": "integer"
+              },
+              "named": {
+                "description": "Answers that name the brand.",
+                "type": "integer"
+              }
+            },
+            "required": [
+              "answers",
+              "named",
+              "cited"
+            ],
+            "type": "object"
+          },
+          "question": {
+            "type": "string"
+          },
+          "since": {
+            "additionalProperties": false,
+            "properties": {
+              "answers": {
+                "type": "integer"
+              },
+              "cited": {
+                "description": "Answers that cite the page.",
+                "type": "integer"
+              },
+              "named": {
+                "description": "Answers that name the brand.",
+                "type": "integer"
+              }
+            },
+            "required": [
+              "answers",
+              "named",
+              "cited"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "question",
+          "before",
+          "since"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "targets",
+    "crawlers"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / data / properties / play / properties / pages / items / properties / live_url
```
Added value: +{
+  "type": "string"
+}
```
removedOutput schema / properties / data / properties / play / properties / pages / items / properties / published_url
```
Removed value: -{
-  "type": "string"
-}
```
addedOutput schema / properties / data / properties / play / properties / pages / items / properties / status / description
```
Added value: +"drafting, sent, live, or revising."
```

changedOutput schema / properties / data / properties / play / properties / pages / items / required

Previous value: -[
-  "page_id",
-  "title",
-  "status",
-  "published_url"
-]New value: +[
+  "page_id",
+  "title",
+  "status",
+  "live_url"
+]

Changed1 schema field changedOct 7, 2026

changedOutput schema / properties / data / required

Previous value: -[
-  "brand",
-  "id",
-  "kind",
-  "stage",
-  "title",
-  "signal",
-  "segment",
-  "monthly_ai_searches",
-  "score",
-  "assignee",
-  "found_at",
-  "stage_changed_at",
-  "snoozed_until",
-  "dismissed_at",
-  "comment_count",
-  "app_url",
-  "facts",
-  "play",
-  "presence",
-  "omitted_competitors",
-  "excerpts",
-  "engine_answers",
-  "sources",
-  "trend",
-  "proof",
-  "timeline",
-  "comments"
-]New value: +[
+  "id",
+  "kind",
+  "stage",
+  "title",
+  "signal",
+  "segment",
+  "monthly_ai_searches",
+  "score",
+  "assignee",
+  "found_at",
+  "stage_changed_at",
+  "snoozed_until",
+  "dismissed_at",
+  "comment_count",
+  "brand",
+  "app_url",
+  "facts",
+  "play",
+  "presence",
+  "omitted_competitors",
+  "excerpts",
+  "engine_answers",
+  "sources",
+  "trend",
+  "proof",
+  "timeline",
+  "comments"
+]

Changed6 schema fields changedOct 3, 2026

addedOutput schema / properties / data / properties / proof / properties / after / properties / high

Added value: +{
+  "description": "High end of the range the value likely sits in (95%).",
+  "type": [
+    "null",
+    "number"
+  ]
+}

addedOutput schema / properties / data / properties / proof / properties / after / properties / low

Added value: +{
+  "description": "Low end of the range the value likely sits in (95%).",
+  "type": [
+    "null",
+    "number"
+  ]
+}

addedOutput schema / properties / data / properties / proof / properties / before / properties / high

Added value: +{
+  "description": "High end of the range the value likely sits in (95%).",
+  "type": [
+    "null",
+    "number"
+  ]
+}

addedOutput schema / properties / data / properties / proof / properties / before / properties / low

Added value: +{
+  "description": "Low end of the range the value likely sits in (95%).",
+  "type": [
+    "null",
+    "number"
+  ]
+}

addedOutput schema / properties / data / properties / proof / properties / changed

Added value: +{
+  "description": "Whether the after rate differs from the before rate by more than chance. Until then: too early to tell.",
+  "type": "boolean"
+}

changedOutput schema / properties / data / properties / proof / required

Previous value: -[
-  "since",
-  "metric",
-  "before",
-  "after",
-  "gap_closed_at",
-  "suggest_won"
-]New value: +[
+  "since",
+  "metric",
+  "before",
+  "after",
+  "changed",
+  "gap_closed_at",
+  "suggest_won"
+]

Changed5 schema fields changedOct 1, 2026

addedOutput schema / properties / data / properties / app_url

Added value: +{
+  "description": "This opportunity in the Cleotic app.",
+  "type": "string"
+}

addedOutput schema / properties / data / properties / omitted_competitors

Added value: +{
+  "description": "Content gaps: competitors named in the window but absent from every model's latest answer, so not listed in presence.",
+  "type": "integer"
+}

changedOutput schema / properties / data / properties / presence / description

Previous value: -"Content gaps: how each model's latest answer treats each brand it names."New value: +"Content gaps: how each model's latest answer treats you and the competitors those answers name, up to six."

changed

Output schema / properties / data / properties / presence / items / properties / models / items / properties / presence / description

Previous value: -"ranked, mentioned, caveated, or absent."New value: +"ranked (with rank), recommended (no rank position), mentioned, caveated, or absent."

changedOutput schema / properties / data / required

Previous value: -[
-  "brand",
-  "id",
-  "kind",
-  "stage",
-  "title",
-  "signal",
-  "segment",
-  "monthly_ai_searches",
-  "score",
-  "assignee",
-  "found_at",
-  "stage_changed_at",
-  "snoozed_until",
-  "dismissed_at",
-  "comment_count",
-  "facts",
-  "play",
-  "presence",
-  "excerpts",
-  "engine_answers",
-  "sources",
-  "trend",
-  "proof",
-  "timeline",
-  "comments"
-]New value: +[
+  "brand",
+  "id",
+  "kind",
+  "stage",
+  "title",
+  "signal",
+  "segment",
+  "monthly_ai_searches",
+  "score",
+  "assignee",
+  "found_at",
+  "stage_changed_at",
+  "snoozed_until",
+  "dismissed_at",
+  "comment_count",
+  "app_url",
+  "facts",
+  "play",
+  "presence",
+  "omitted_competitors",
+  "excerpts",
+  "engine_answers",
+  "sources",
+  "trend",
+  "proof",
+  "timeline",
+  "comments"
+]

Changed4 schema fields changedOct 1, 2026

addedInput schema / additionalProperties
```
Added value: +false
```
addedInput schema / properties / brand / minLength
```
Added value: +1
```
addedInput schema / properties / opportunity_id / minLength
```
Added value: +1
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "assignee": {
+          "additionalProperties": false,
+          "properties": {
+            "member_id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "member_id",
+            "name"
+          ],
+          "type": [
+            "null",
+            "object"
+          ]
+        },
+        "brand": {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "url": {
+              "description": "The brand's website, or empty when none is set.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "url"
+          ],
+          "type": "object"
+        },
+        "comment_count": {
+          "type": "integer"
+        },
+        "comments": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "author": {
+                "type": "string"
+              },
+              "body": {
+                "type": "string"
+              },
+              "created_at": {
+                "type": "string"
+              },
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "body",
+              "author",
+              "created_at"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "dismissed_at": {
+          "type": "string"
+        },
+        "engine_answers": {
+          "description": "Content gaps: each model's latest answer to the question.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "answer_id": {
+                "description": "get_answer gives the full text.",
+                "type": "string"
+              },
+              "brands_named": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "captured_at": {
+                "type": "string"
+              },
+              "model": {
+                "type": "string"
+              },
+              "model_name": {
+                "type": "string"
+              },
+              "names_you": {
+                "type": "boolean"
+              },
+              "opening": {
+                "description": "The answer's first lines.",
+                "type": "string"
+              }
+            },
+            "required": [
+              "answer_id",
+              "model",
+              "model_name",
+              "captured_at",
+              "names_you",
+              "brands_named",
+              "opening"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "excerpts": {
+          "description": "Verbatim answer excerpts behind the opportunity.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "answer_id": {
+                "type": "string"
+              },
+              "captured_at": {
+                "type": "string"
+              },
+              "model": {
+                "type": "string"
+              },
+              "model_name": {
+                "type": "string"
+              },
+              "text": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "answer_id",
+              "model",
+              "model_name",
+              "captured_at",
+              "text"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "facts": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "label": {
+                "type": "string"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "label",
+              "value"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "found_at": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "kind": {
+          "description": "content_gap, readiness, source_gap, traffic_gap, or coverage_gap.",
+          "type": "string"
+        },
+        "monthly_ai_searches": {
+          "type": [
+            "null",
+            "integer"
+          ]
+        },
+        "play": {
+          "additionalProperties": false,
+          "description": "What to do about it.",
+          "properties": {
+            "angle": {
+              "type": "string"
+            },
+            "changes": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "check_id": {
+              "type": "string"
+            },
+            "checklist": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "done": {
+                    "type": "boolean"
+                  },
+                  "id": {
+                    "type": "string"
+                  },
+                  "label": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "id",
+                  "label",
+                  "done"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "findings": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "check_id": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "check_id",
+                  "title"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "fix_language": {
+              "type": "string"
+            },
+            "fix_snippet": {
+              "type": "string"
+            },
+            "headline": {
+              "type": "string"
+            },
+            "kind": {
+              "description": "draft_content, ship_fix, earn_source, optimise_page, or track_prompts.",
+              "type": "string"
+            },
+            "next_step": {
+              "description": "The tool call that carries out the play.",
+              "type": "string"
+            },
+            "optimised_at": {
+              "type": "string"
+            },
+            "outreach": {
+              "additionalProperties": false,
+              "properties": {
+                "body": {
+                  "type": "string"
+                },
+                "error": {
+                  "type": "string"
+                },
+                "generated_at": {
+                  "type": "string"
+                },
+                "status": {
+                  "description": "none, generating, ready, or failed.",
+                  "type": "string"
+                },
+                "subject": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "status",
+                "subject",
+                "body",
+                "generated_at",
+                "error"
+              ],
+              "type": [
+                "null",
+                "object"
+              ]
+            },
+            "page_ideas": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "content_type": {
+                    "type": "string"
+                  },
+                  "covered": {
+                    "description": "An existing page already covers it.",
+                    "type": "boolean"
+                  },
+                  "objective": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "title",
+                  "content_type",
+                  "objective",
+                  "covered"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "pages": {
+              "description": "draft_content: Content Studio pages already started for it.",
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "page_id": {
+                    "type": "string"
+                  },
+                  "published_url": {
+                    "type": "string"
+                  },
+                  "status": {
+                    "type": "string"
+                  },
+                  "title": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "page_id",
+                  "title",
+                  "status",
+                  "published_url"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "pitched_at": {
+              "type": "string"
+            },
+            "segment": {
+              "additionalProperties": false,
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "name"
+              ],
+              "type": [
+                "null",
+                "object"
+              ]
+            },
+            "shipped_at": {
+              "type": "string"
+            },
+            "suggestions": {
+              "description": "track_prompts: questions to track; pass their suggestion_id to act_on_opportunity.",
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "monthly_ai_searches": {
+                    "type": [
+                      "null",
+                      "integer"
+                    ]
+                  },
+                  "seen_count": {
+                    "type": "integer"
+                  },
+                  "suggestion_id": {
+                    "type": "string"
+                  },
+                  "text": {
+                    "type": "string"
+                  },
+                  "tracked": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "suggestion_id",
+                  "text",
+                  "monthly_ai_searches",
+                  "seen_count",
+                  "tracked"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "target": {
+              "additionalProperties": false,
+              "properties": {
+                "source_id": {
+                  "description": "Pass to get_citation_source.",
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "source_id",
+                "title",
+                "url"
+              ],
+              "type": [
+                "null",
+                "object"
+              ]
+            },
+            "tracked_at": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "kind",
+            "headline",
+            "next_step"
+          ],
+          "type": [
+            "null",
+            "object"
+          ]
+        },
+        "presence": {
+          "description": "Content gaps: how each model's latest answer treats each brand it names.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "brand": {
+                "additionalProperties": false,
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "url": {
+                    "description": "The brand's website, or empty when none is set.",
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "id",
+                  "name",
+                  "url"
+                ],
+                "type": "object"
+              },
+              "is_you": {
+                "type": "boolean"
+              },
+              "models": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "model": {
+                      "type": "string"
+                    },
+                    "model_name": {
+                      "type": "string"
+                    },
+                    "presence": {
+                      "description": "ranked, mentioned, caveated, or absent.",
+                      "type": "string"
+                    },
+                    "rank": {
+                      "type": [
+                        "null",
+                        "integer"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "model",
+                    "model_name",
+                    "presence",
+                    "rank"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "brand",
+              "is_you",
+              "models"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "proof": {
+          "additionalProperties": false,
+          "description": "Before and after the play, once it shipped.",
+          "properties": {
+            "after": {
+              "additionalProperties": false,
+              "properties": {
+                "answers": {
+                  "type": "integer"
+                },
+                "period": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "description": "First day, YYYY-MM-DD.",
+                      "type": "string"
+                    },
+                    "to": {
+                      "description": "Last day, YYYY-MM-DD.",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "from",
+                    "to"
+                  ],
+                  "type": "object"
+                },
+                "value": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "value",
+                "answers",
+                "period"
+              ],
+              "type": [
+                "null",
+                "object"
+              ]
+            },
+            "before": {
+              "additionalProperties": false,
+              "properties": {
+                "answers": {
+                  "type": "integer"
+                },
+                "period": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "description": "First day, YYYY-MM-DD.",
+                      "type": "string"
+                    },
+                    "to": {
+                      "description": "Last day, YYYY-MM-DD.",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "from",
+                    "to"
+                  ],
+                  "type": "object"
+                },
+                "value": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "value",
+                "answers",
+                "period"
+              ],
+              "type": [
+                "null",
+                "object"
+              ]
+            },
+            "gap_closed_at": {
+              "type": "string"
+            },
+            "metric": {
+              "type": "string"
+            },
+            "since": {
+              "type": "string"
+            },
+            "suggest_won": {
+              "description": "The gap has closed; move the opportunity to won.",
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "since",
+            "metric",
+            "before",
+            "after",
+            "gap_closed_at",
+            "suggest_won"
+          ],
+          "type": [
+            "null",
+            "object"
+          ]
+        },
+        "score": {
+          "description": "0-100 priority.",
+          "type": "integer"
+        },
+        "segment": {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name"
+          ],
+          "type": [
+            "null",
+            "object"
+          ]
+        },
+        "signal": {
+          "description": "Why it matters now.",
+          "type": "string"
+        },
+        "snoozed_until": {
+          "type": "string"
+        },
+        "sources": {
+          "description": "Sources the answers cite.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "citations": {
+                "type": "integer"
+              },
+              "domain": {
+                "type": "string"
+              },
+              "ownership": {
+                "description": "own, competitor, or third_party.",
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "domain",
+              "url",
+              "title",
+              "ownership",
+              "citations"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "stage": {
+          "description": "now, in_flight, watching, or won.",
+          "type": "string"
+        },
+        "stage_changed_at": {
+          "type": "string"
+        },
+        "timeline": {
+          "description": "The 10 latest events, newest first.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "at": {
+                "type": "string"
+              },
+              "by": {
+                "type": "string"
+              },
+              "detail": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "at",
+              "by",
+              "detail"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "title": {
+          "type": "string"
+        },
+        "trend": {
+          "additionalProperties": false,
+          "properties": {
+            "marker": {
+              "description": "When the play shipped, if it has.",
+              "type": "string"
+            },
+            "metric": {
+              "description": "mention_rate, recommendation_rate, or ai_referrals.",
+              "type": "string"
+            },
+            "points": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "date": {
+                    "type": "string"
+                  },
+                  "value": {
+                    "type": "number"
+                  }
+                },
+                "required": [
+                  "date",
+                  "value"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "metric",
+            "points",
+            "marker"
+          ],
+          "type": [
+            "null",
+            "object"
+          ]
+        }
+      },
+      "required": [
+        "brand",
+        "id",
+        "kind",
+        "stage",
+        "title",
+        "signal",
+        "segment",
+        "monthly_ai_searches",
+        "score",
+        "assignee",
+        "found_at",
+        "stage_changed_at",
+        "snoozed_until",
+        "dismissed_at",
+        "comment_count",
+        "facts",
+        "play",
+        "presence",
+        "excerpts",
+        "engine_answers",
+        "sources",
+        "trend",
+        "proof",
+        "timeline",
+        "comments"
+      ],
+      "type": "object"
+    },
+    "generated_at": {
+      "description": "RFC 3339 time the response was made.",
+      "type": "string"
+    },
+    "schema_version": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "schema_version",
+    "generated_at",
+    "data"
+  ],
+  "type": "object"
+}

AddedSep 30, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful context about the shape of the payload (evidence, play, the tool call that carries it out, proof, timeline, comments) rather than restating the annotations. It stops short of disclosing anything about auth, freshness, or rate limits, but the bar is lower here.

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

Conciseness4/5

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

Front-loaded with the core purpose, and the routing guidance lands in the final sentence where it is easy to find. The long parenthetical content list is dense but each item is informative; only slight trimming would be possible.

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

Completeness5/5

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

With an output schema present, the description need not explain return values, yet it still orients the agent on payload richness. Combined with full parameter coverage and annotations covering safety, nothing an agent needs to call this correctly is missing.

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 100% and both params are documented in-schema (brand resolvable from list_brands, opportunity_id from list_opportunities). The description adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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 specific verb and resource ('One opportunity') and then enumerates precisely what the payload contains — evidence, play, tool call, before/after proof, timeline, comments — so the agent knows exactly what it gets. It is clearly distinguished from list_opportunities (browsing) and act_on_opportunity/create_page (acting), which appear in sibling tool names.

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

Usage Guidelines5/5

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

Gives an explicit sequencing rule ('Read it before act_on_opportunity or create_page') and names the alternative for the other mode ('to browse the inbox use list_opportunities'). Both when-to-use and when-to-use-something-else are stated, leaving nothing to inference.

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

All Cleotic tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?