Cleotic

Save segment

save_segment

Add a segment (a market and language to track), or with segment edit one or pause and resume it. A segment can carry an audience on the Business plan: a buyer described by situation (budget, role, company size, home, priorities) that is sent with every prompt as an 'About me' line, so answers show what the engines tell that buyer; Google AI Overviews and AI Mode are not collected for it. To compare an audience with an existing segment, create a new segment with copy_prompts_from and an audience. Cost: an active segment is plan capacity and collects daily from every plan model, using model budget; copied prompts each use one prompt of plan capacity.

Input Schema

Name	Required	Description
`geo`	No	Country code, for example GB, or global: where this segment's answers are collected from.
`name`	No
`brand`	Yes	Brand or study: its ID from list_brands, or its exact name. A partial name is refused.
`status`	No
`segment`	No	Edit this segment (ID or name). Leave out to add one.
`audience`	No	The buyer this segment's prompts are asked as. Replaces the current audience. Describe needs and situation: age and gender alone rarely change answers.
`language`	No	Language code, for example en.
`prompt_limit`	No
`idempotency_key`	Yes	A unique key for this intended action. Reuse it with identical arguments when retrying: the write is not made again, and the reply is the first call's resource as saved (replayed: true) with current status; read tools show the resource's current state. Use a new key for another action.
`audience_template`	No	Start from a built-in audience instead of passing audience; none removes the audience.
`copy_prompts_from`	No	New segments only: copy this segment's (ID or name) active prompts, market and language into the new segment, so the two can be compared.

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.

Changed1 schema field changedOct 13, 2026

changedOutput schema / properties / data / properties / cost / properties / content_generations / description

Previous value: -"Content Studio generations used from the plan's allowance."New value: +"Content Studio pages or outreach drafts used from the plan's allowance."

Changed7 schema fields changedOct 13, 2026

addedInput schema / properties / audience

Added value: +{
+  "additionalProperties": false,
+  "description": "The buyer this segment's prompts are asked as. Replaces the current audience. Describe needs and situation: age and gender alone rarely change answers.",
+  "properties": {
+    "age_band": {
+      "enum": [
+        "18_24",
+        "25_34",
+        "35_44",
+        "45_54",
+        "55_64",
+        "65_plus"
+      ],
+      "type": "string"
+    },
+    "budget": {
+      "enum": [
+        "comfortable",
+        "moderate",
+        "tight"
+      ],
+      "type": "string"
+    },
+    "company_complexity": {
+      "enum": [
+        "multi_entity",
+        "multinational",
+        "single_entity"
+      ],
+      "type": "string"
+    },
+    "company_size": {
+      "enum": [
+        "1000_plus",
+        "11_50",
+        "201_1000",
+        "2_10",
+        "51_200",
+        "solo"
+      ],
+      "type": "string"
+    },
+    "expertise": {
+      "enum": [
+        "expert",
+        "novice",
+        "some"
+      ],
+      "type": "string"
+    },
+    "gender": {
+      "enum": [
+        "man",
+        "non_binary",
+        "woman"
+      ],
+      "type": "string"
+    },
+    "home": {
+      "enum": [
+        "owns_flat",
+        "owns_house",
+        "renting_home",
+        "renting_room"
+      ],
+      "type": "string"
+    },
+    "household": {
+      "enum": [
+        "alone",
+        "couple",
+        "multi_generational",
+        "shared_house",
+        "teenagers",
+        "young_children"
+      ],
+      "type": "string"
+    },
+    "industry": {
+      "enum": [
+        "charity",
+        "construction_trades",
+        "education",
+        "financial_services",
+        "healthcare",
+        "hospitality",
+        "manufacturing",
+        "other",
+        "professional_services",
+        "public_sector",
+        "retail_ecommerce",
+        "software"
+      ],
+      "type": "string"
+    },
+    "kind": {
+      "enum": [
+        "consumer",
+        "business"
+      ],
+      "type": "string"
+    },
+    "label": {
+      "maxLength": 60,
+      "type": "string"
+    },
+    "occupation": {
+      "enum": [
+        "carer",
+        "employed",
+        "retired",
+        "self_employed",
+        "student",
+        "unemployed"
+      ],
+      "type": "string"
+    },
+    "priorities": {
+      "items": {
+        "enum": [
+          "customer_service",
+          "integrations",
+          "lowest_price",
+          "mobile",
+          "predictable_costs",
+          "premium_quality",
+          "quick_setup",
+          "reporting_controls",
+          "simplicity",
+          "sustainability"
+        ],
+        "type": "string"
+      },
+      "maxItems": 3,
+      "type": "array"
+    },
+    "role": {
+      "enum": [
+        "executive",
+        "finance",
+        "founder_owner",
+        "hr",
+        "it_engineering",
+        "marketing",
+        "operations",
+        "procurement",
+        "sales"
+      ],
+      "type": "string"
+    },
+    "seniority": {
+      "enum": [
+        "c_level",
+        "director",
+        "individual",
+        "manager"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind"
+  ],
+  "type": "object"
+}

addedInput schema / properties / audience_template

Added value: +{
+  "description": "Start from a built-in audience instead of passing audience; none removes the audience.",
+  "enum": [
+    "budget_student",
+    "young_professional",
+    "young_family",
+    "comfortable_retiree",
+    "eco_household",
+    "startup_founder",
+    "sole_trader",
+    "mid_market_manager",
+    "enterprise_finance",
+    "technical_evaluator",
+    "none"
+  ],
+  "type": "string"
+}

addedInput schema / properties / copy_prompts_from

Added value: +{
+  "description": "New segments only: copy this segment's (ID or name) active prompts, market and language into the new segment, so the two can be compared.",
+  "maxLength": 4096,
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / data / properties / resource / properties / audience

Added value: +{
+  "additionalProperties": false,
+  "description": "The buyer the segment's prompts are asked as, or null when answers are collected for an anonymous user.",
+  "properties": {
+    "age_band": {
+      "type": "string"
+    },
+    "archetype": {
+      "type": "string"
+    },
+    "budget": {
+      "type": "string"
+    },
+    "company_complexity": {
+      "type": "string"
+    },
+    "company_size": {
+      "type": "string"
+    },
+    "expertise": {
+      "type": "string"
+    },
+    "gender": {
+      "type": "string"
+    },
+    "home": {
+      "type": "string"
+    },
+    "household": {
+      "type": "string"
+    },
+    "industry": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "label": {
+      "type": "string"
+    },
+    "occupation": {
+      "type": "string"
+    },
+    "priorities": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "role": {
+      "type": "string"
+    },
+    "seniority": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind"
+  ],
+  "type": [
+    "null",
+    "object"
+  ]
+}

addedOutput schema / properties / data / properties / resource / properties / audience_text

Added value: +{
+  "description": "The 'About me' line sent with every prompt in the segment; empty without an audience.",
+  "type": "string"
+}

changedOutput schema / properties / data / properties / resource / properties / models / description

Previous value: -"The AI models the segment collects from: every model the plan covers."New value: +"The AI models the segment collects from: every model the plan covers, except Google AI Overviews and AI Mode for a segment with an audience."

changedOutput schema / properties / data / properties / resource / required

Previous value: -[
-  "id",
-  "name",
-  "status",
-  "market",
-  "language",
-  "prompt_limit",
-  "prompt_count",
-  "models"
-]New value: +[
+  "id",
+  "name",
+  "status",
+  "market",
+  "language",
+  "audience",
+  "audience_text",
+  "prompt_limit",
+  "prompt_count",
+  "models"
+]

Changed1 schema field changedOct 7, 2026

changedOutput schema / properties / data / properties / resource / properties / status / description

Previous value: -"active segments collect on Mondays, Wednesdays and Fridays; paused ones do not."New value: +"active segments collect daily; paused ones do not."

Changed7 schema fields changedOct 1, 2026

changedInput schema / properties / brand / description

Previous value: -"Brand or study: its ID from list_brands, or its name."New value: +"Brand or study: its ID from list_brands, or its exact name. A partial name is refused."

changedInput schema / properties / geo / description

Previous value: -"Country code, for example GB."New value: +"Country code, for example GB, or global: where this segment's answers are collected from."

changedInput schema / properties / idempotency_key / description

Previous value: -"A unique key for this intended action. Reuse it with identical arguments when retrying; use a new key for another action."New value: +"A unique key for this intended action. Reuse it with identical arguments when retrying: the write is not made again, and the reply is the first call's resource as saved (replayed: true) with current status; read tools show the resource's current state. Use a new key for another action."

changedOutput schema / properties / data / properties / brand / description

Previous value: -"The brand written to; null for brand setup before approval."New value: +"The brand written to; null for start_brand_setup, which has no brand yet."

changedOutput schema / properties / data / properties / cost / properties / readiness_scans / description

Previous value: -"Site readiness scans used from the plan's monthly allowance."New value: +"Full site readiness scans started; counted for the month, with no monthly allowance."

addedOutput schema / properties / data / properties / created_at

Added value: +{
+  "description": "Set on a replay: when the original call was made.",
+  "type": "string"
+}

changedOutput schema / properties / data / properties / replayed / description

Previous value: -"True when this repeats an earlier call with the same idempotency_key."New value: +"True when this repeats an earlier call with the same idempotency_key. The write is not made again: resource is as first saved, status, progress and message are current, and the read tools show the resource's current state."

Changed1 schema field changedOct 1, 2026

changedOutput schema / properties / data / properties / resource / properties / status / description

Previous value: -"active segments collect daily; paused ones do not."New value: +"active segments collect on Mondays, Wednesdays and Fridays; paused ones do not."

Changed1 schema field changedOct 1, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "data": {
+      "additionalProperties": false,
+      "properties": {
+        "brand": {
+          "additionalProperties": false,
+          "description": "The brand written to; null for brand setup before approval.",
+          "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": [
+            "null",
+            "object"
+          ]
+        },
+        "cost": {
+          "additionalProperties": false,
+          "description": "What the write used from the plan's capacity, allowances and model budget; null when nothing.",
+          "properties": {
+            "content_generations": {
+              "description": "Content Studio generations used from the plan's allowance.",
+              "type": "integer"
+            },
+            "model_budget": {
+              "description": "Whether the call spends the organisation's AI model budget.",
+              "type": "boolean"
+            },
+            "note": {
+              "type": "string"
+            },
+            "prompt_capacity": {
+              "description": "Active prompts added against the plan's prompt limit.",
+              "type": "integer"
+            },
+            "queued_model_runs": {
+              "description": "Answer collections queued; each uses model budget.",
+              "type": "integer"
+            },
+            "readiness_checks": {
+              "description": "Readiness re-checks used from the plan's monthly allowance.",
+              "type": "integer"
+            },
+            "readiness_scans": {
+              "description": "Site readiness scans used from the plan's monthly allowance.",
+              "type": "integer"
+            }
+          },
+          "required": [
+            "model_budget",
+            "content_generations",
+            "readiness_scans",
+            "readiness_checks",
+            "prompt_capacity",
+            "queued_model_runs",
+            "note"
+          ],
+          "type": [
+            "null",
+            "object"
+          ]
+        },
+        "message": {
+          "description": "What happens next.",
+          "type": "string"
+        },
+        "operation_id": {
+          "description": "Pass to get_operation to follow the write.",
+          "type": "string"
+        },
+        "poll_after_seconds": {
+          "description": "While pending, how long to wait before calling get_operation; 0 otherwise.",
+          "type": "integer"
+        },
+        "progress": {
+          "additionalProperties": false,
+          "description": "Set while the work runs.",
+          "properties": {
+            "done": {
+              "type": "integer"
+            },
+            "message": {
+              "type": "string"
+            },
+            "stage": {
+              "type": "string"
+            },
+            "total": {
+              "description": "0 when the total is not known.",
+              "type": "integer"
+            }
+          },
+          "required": [
+            "stage",
+            "done",
+            "total",
+            "message"
+          ],
+          "type": [
+            "null",
+            "object"
+          ]
+        },
+        "replayed": {
+          "description": "True when this repeats an earlier call with the same idempotency_key.",
+          "type": "boolean"
+        },
+        "resource": {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "language": {
+              "description": "Language code, or empty for the market's default.",
+              "type": "string"
+            },
+            "market": {
+              "description": "Country code, or global.",
+              "type": "string"
+            },
+            "models": {
+              "description": "The AI models the segment collects from: every model the plan covers.",
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "model": {
+                    "description": "Model family key.",
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "model",
+                  "name"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "name": {
+              "type": "string"
+            },
+            "prompt_count": {
+              "type": "integer"
+            },
+            "prompt_limit": {
+              "type": "integer"
+            },
+            "status": {
+              "description": "active segments collect daily; paused ones do not.",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "status",
+            "market",
+            "language",
+            "prompt_limit",
+            "prompt_count",
+            "models"
+          ],
+          "type": "object"
+        },
+        "status": {
+          "description": "completed: done. pending: saved, with work still running; call get_operation after poll_after_seconds. failed: the work after the write failed; message says why.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "operation_id",
+        "status",
+        "replayed",
+        "brand",
+        "resource",
+        "progress",
+        "poll_after_seconds",
+        "message",
+        "cost"
+      ],
+      "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

A3.9/5.0

Behavior4/5

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

Annotations already declare openWorldHint=true, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real context the annotations cannot: an active segment consumes plan capacity and collects daily from every plan model against model budget, copied prompts each consume one prompt of capacity, and Google AI Overviews/AI Mode are excluded from collection. That is genuinely useful cost and coverage disclosure.

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?

The content is dense and earns its place, but it is delivered as one long, run-on paragraph with several stacked clauses per sentence, and the opening sentence is awkward to parse. Front-loading of the core action is decent, but readability suffers.

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?

With an output schema present, return values need not be explained, and annotations cover the mutation/safety profile. The description fills the remaining gaps — modes, audience semantics, comparison workflow, and cost — so an agent has enough to call it correctly, though geo/language/brand usage is left entirely to the schema.

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

Parameters4/5

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

Schema coverage is 73%, so the schema carries most parameter detail; the description still adds meaning the schema does not, explaining that 'audience' is the buyer prompts are asked as, that 'age and gender alone rarely change answers', and that copy_prompts_from exists to enable segment comparison. Undescribed fields (brand, geo, language, prompt_limit) are adequately covered by inline schema descriptions.

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

Purpose4/5

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

The description names a specific verb+resource (segment) and enumerates its modes: add, edit (via 'segment'), and pause/resume via status. It distinguishes itself from nearby write tools like save_prompt and save_competitor by describing what a segment actually contains (market + language). The first sentence is slightly garbled ('or with segment edit one or pause and resume it'), which keeps it from a 5.

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?

It gives conditional guidance: leave out 'segment' to add, pass it to edit, use status to pause/resume, and create a new segment with copy_prompts_from to compare audiences. That covers when-to-use for each mode, though it never names a sibling alternative or an explicit 'do not use this for X' case.

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?