get_brand_setupA brand setup's progress and, once it needs approval, its proposals: the brand, competitors, segment, and prompts, each with the proposal_id approve_brand_setup takes.
| Name | Required | Description | Default |
|---|---|---|---|
| setup_id | Yes | Setup ID from start_brand_setup. |
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| generated_at | Yes | RFC 3339 time the response was made. | |
| schema_version | Yes |
Changes observed during successful MCP inspections.
Output schema / properties / data / properties / competitors / items / properties / status / descriptionPrevious value: -"pending; superseded when its site could not be assessed; accepted or rejected once approved."New value: +"pending, or accepted or rejected once approved. Superseded proposals are not listed while the setup is open."Output schema / properties / data / properties / segment / properties / market / descriptionAdded value: +"An upper-case country code such as AE, or global. Confirm it with the user: pass it as approve_brand_setup's market, with kind country and this code, or kind global."Output schema / properties / data / properties / segment / properties / market_labelAdded value: +{
+ "description": "The market's name, for example United Arab Emirates; pass as market.label.",
+ "type": "string"
+}Output schema / properties / data / properties / segment / requiredPrevious value: -[
- "name",
- "market",
- "language"
-]New value: +[
+ "name",
+ "market",
+ "market_label",
+ "language"
+]Input schema / additionalPropertiesAdded value: +falseInput schema / properties / setup_id / minLengthAdded value: +1Output schema / (root)Previous value: -nullNew value: +{
+ "additionalProperties": false,
+ "properties": {
+ "data": {
+ "additionalProperties": false,
+ "properties": {
+ "brand": {
+ "additionalProperties": false,
+ "description": "The proposed brand.",
+ "properties": {
+ "aliases": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "name": {
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "url",
+ "aliases"
+ ],
+ "type": [
+ "null",
+ "object"
+ ]
+ },
+ "brand_id": {
+ "description": "The created brand, once committed.",
+ "type": "string"
+ },
+ "competitors": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "aliases": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "name": {
+ "type": "string"
+ },
+ "proposal_id": {
+ "description": "Pass in accepted_brand_proposal_ids to keep it.",
+ "type": "string"
+ },
+ "status": {
+ "description": "pending; superseded when its site could not be assessed; accepted or rejected once approved.",
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ },
+ "warning": {
+ "description": "Why tracking its site may not work.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "proposal_id",
+ "name",
+ "url",
+ "aliases",
+ "status",
+ "warning"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "error": {
+ "description": "Set when failed: site_unreachable, no_brand_found, timed_out, or failed.",
+ "type": "string"
+ },
+ "poll_after_seconds": {
+ "description": "While reading, how long to wait before reading again; 0 otherwise.",
+ "type": "integer"
+ },
+ "prompts": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "proposal_id": {
+ "description": "Pass in accepted_prompt_proposal_ids to keep it.",
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ },
+ "tags": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "text": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "proposal_id",
+ "text",
+ "tags",
+ "status"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "segment": {
+ "additionalProperties": false,
+ "properties": {
+ "language": {
+ "type": "string"
+ },
+ "market": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "market",
+ "language"
+ ],
+ "type": [
+ "null",
+ "object"
+ ]
+ },
+ "setup_id": {
+ "type": "string"
+ },
+ "status": {
+ "description": "reading (poll), needs_approval (review, then approve_brand_setup), committed, failed, rejected, or cancelled.",
+ "type": "string"
+ },
+ "step": {
+ "description": "While reading: site, brand, questions, then ready.",
+ "type": "string"
+ },
+ "url": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "setup_id",
+ "status",
+ "step",
+ "error",
+ "url",
+ "brand_id",
+ "brand",
+ "competitors",
+ "segment",
+ "prompts",
+ "poll_after_seconds"
+ ],
+ "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"
+}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds a genuine behavioral nuance beyond them: proposals are only present 'once it needs approval', so the payload is state-dependent. That is useful context an agent cannot get from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single compact sentence, so nothing is wasted, but the nested 'progress and, once it needs approval, its proposals' clause plus the trailing relative clause makes it dense and slightly awkward to parse. Front-loading the resource is good; the structure could be cleaner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich annotation set and an existing output schema, the description need not enumerate return fields, and it correctly focuses on the setup lifecycle and proposal availability. Only minor gaps remain, such as behavior when the setup is not yet at the approval stage or when setup_id is invalid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage, and the schema already tells the agent the id comes from start_brand_setup. The description alludes to 'a brand setup's' but adds no syntax or constraint detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific resource (a brand setup) and what is retrieved (progress, and its proposals once approval is needed), which distinguishes it from get_brand_overview and get_brand_settings. It is a noun fragment rather than a verb+resource statement, but an agent can still tell what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call this to read a setup's progress, and once it reaches the approval stage to obtain proposal_ids. It names approve_brand_setup as the consumer of those ids, but gives no when-not guidance or explicit alternative for reading brand data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.