Creative performance, tag-level insights, attribution data, and competitor ad analysis from Segwise. Connect with your Segwise account using OAuth.
Scored across 3 tools
The three tools map cleanly to distinct roles: discover organizations, launch an async query, and poll that query. The main friction is that start_segwise_query and get_segwise_query both carry nearly identical, very long polling/lifecycle prose, which blurs the line between 'launch' and 'poll' and makes the descriptions harder to distinguish than they need to be, though the underlying actions remain separate.
All three tools follow a single predictable pattern: verb + 'segwise' + noun (get_segwise_query, list_segwise_organizations, start_segwise_query). Verb choice is semantically accurate per action, and there is no mixing of casing or verb styles.
A three-tool start/poll/context surface is well scoped for an async analysis backend and each tool earns its place. It leans slightly thin, since job management (cancel, list jobs) has no dedicated entry point, but nothing extraneous is present.
The core async lifecycle (org discovery -> start -> poll to completion) is covered, but there is no way to cancel a long-running query, list prior queries/conversations, or retrieve a completed job by ID without re-polling. The conversation_id machinery implies a resumable history that the surface cannot actually browse, which is a notable gap for multi-turn use.
Wait for and retrieve a Segwise query started by start_segwise_query. Pass the returned job_id unchanged. This call waits for up to 25 seconds for the query to finish; if status is still running, call it again. Queries can take several minutes and many status checks. A running status means the query is still executing, not that it failed or has no data. Keep calling get_segwise_query with the exact same job_id, respecting poll_after_seconds. Do not start a duplicate query or stop because repeated checks return running. Give brief progress updates while continuing to poll; do not finish with a still-running answer while polling remains available. Stop polling on completed, failed, execution_deadline, an unrecoverable error, or user cancellation. Retry transient status-check errors with bounded backoff and honor retry delays; do not retry authentication or permission failures. If the host prevents further execution, distinguish that interruption from query failure and preserve the job_id for resumption. When status is completed, use the nested result as the answer. Preserve the exact conversation_id and organization_id for follow-ups in the original user's conversation. If delegated, return both IDs unchanged to the parent with the answer and tell it to pass them into later start_segwise_query calls; do not reset merely because a new child agent or subprocess handles the follow-up. Jobs are temporary and may be interrupted by a service restart.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Exact job_id returned by start_segwise_query. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| job_id | Yes | |
| result | No | |
| status | Yes | Running means keep polling the same job. Completed and failed are terminal statuses. |
| message | No | Guidance for continuing this running query. Absent for terminal results. |
| next_action | No | Tool to call next with the same job_id when running. Absent for terminal results. |
| organization_id | Yes | |
| organization_name | Yes | |
| execution_deadline | Yes | Absolute RFC3339 execution deadline set when this query started. Polling does not extend it. Completed results remain retrievable within the result retention window. |
| poll_after_seconds | No | Minimum delay in seconds before the next get_segwise_query call when running. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the 25-second wait window, that queries may take minutes and require many polls, that running does not mean failure or empty data, and that jobs are temporary and can be lost to service restarts. It also covers retry policy (bounded backoff, no retry on auth/permission failures) and host-interruption semantics.
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?
The core instruction is front-loaded in the first two sentences, but the remainder is a long block of overlapping directives that restate the same points ('do not stop because repeated checks return running' appears in several forms). Much of the delegation and conversation_id guidance is situational and dilutes the primary polling loop.
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?
An output schema exists, so return-value explanation is correctly omitted, and the description covers the edge cases that matter for a long-running poll (timeouts, transient errors, auth failures, host interruption, job loss). The one gap is the mention of poll_after_seconds, which has no corresponding schema field, leaving the agent unsure whether such a value exists or where to get it.
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?
Schema coverage is 100% for the single job_id parameter, so the baseline is 3; the description does add meaning by insisting the id be passed unchanged, reused across every poll, and preserved for resumption or delegation. However, it references 'poll_after_seconds', which is not a property in the schema (additionalProperties is false), creating minor confusion about an argument that cannot be supplied.
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 first sentence names a specific verb pair (wait for and retrieve) and the exact resource (a Segwise query started by start_segwise_query), tying it directly to the sibling that creates it. An agent can immediately distinguish this polling/read tool from start_segwise_query and list_segwise_organizations.
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?
Explicit when-to-use and when-to-stop guidance: keep polling on running, stop on completed/failed/execution_deadline/unrecoverable error/user cancellation. It also names the anti-patterns explicitly (do not start a duplicate query, do not stop on repeated running).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the organizations the authenticated user can currently access in Segwise. Present organization names to the user and use the corresponding organization_id only internally in later tool calls; never ask the user to read or type an ID. Use this tool when the user asks which organizations are available, wants to switch organizations, or was recently added to an organization. It requests a membership refresh from PropelAuth, limited to once per user per minute.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| organizations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds value beyond them by disclosing that the call triggers a PropelAuth membership refresh throttled to once per user per minute. That rate-limit and side-effect detail is exactly the kind of context annotations cannot express.
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?
Four sentences, front-loaded with purpose and then layered with usage triggers, handling rules, and the rate limit. Every sentence carries distinct information and none restates the title or annotations.
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?
For a zero-parameter read tool with an output schema and full annotation coverage, nothing material is missing: the description covers when to call it, how to present and reuse results, and the throttling behavior. Return-value structure is correctly left to the output schema.
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?
The tool takes zero parameters, so the baseline is 4. The description still explains how the returned organization_id should be used internally in later calls, which adds useful meaning around the output contract even though no inputs exist to document.
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 opens with a precise verb and resource ('Return the organizations the authenticated user can currently access in Segwise'), which is a distinct resource from the sibling query tools (get_segwise_query, start_segwise_query), so an agent can route without opening either schema.
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?
It names three concrete triggering conditions: the user asking which organizations exist, wanting to switch organizations, or having been recently added to one. It also gives a presentation rule (show names, keep organization_id internal, never ask the user to type an ID), so both selection and follow-up behavior are specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze the authenticated organization's advertising and creative performance using Segwise's internal agent. Use this tool to compare performance and trends by app, campaign, ad network, creative, or creative tag and to analyze metrics including spend, impressions, clicks, installs, CTR, CVR, CPI, CPA, ROAS, revenue, and LTV. It can identify winning, declining, or fatigued creatives; explain which hooks, CTAs, visuals, themes, and formats drive results; and recommend what to scale, pause, refresh, or test next. It cannot modify campaigns or generate creatives. It creates a temporary background query job and may save conversation history. It returns a job_id immediately; call get_segwise_query with that exact job_id until the query reports completed or failed. Queries can take several minutes and many status checks. A running status means the query is still executing, not that it failed or has no data. Keep calling get_segwise_query with the exact same job_id, respecting poll_after_seconds. Do not start a duplicate query or stop because repeated checks return running. Give brief progress updates while continuing to poll; do not finish with a still-running answer while polling remains available. Stop polling on completed, failed, execution_deadline, an unrecoverable error, or user cancellation. Retry transient status-check errors with bounded backoff and honor retry delays; do not retry authentication or permission failures. If the host prevents further execution, distinguish that interruption from query failure and preserve the job_id for resumption. organization_id is optional when exactly one organization is available; when multiple organizations are available, present only organization names to the user, map the chosen name to the corresponding organization_id, and retry without asking the user to read or type an ID. Conversation continuity rule: this host chat means the original user's conversation, including work delegated to child agents or subprocesses. Omit conversation_id on the first query for an organization in that conversation. Otherwise, copy the exact conversation_id and organization_id from the latest start or completed result into every later start_segwise_query call for that organization. Follow-ups such as 'How about last month?' reuse those IDs even when the date range, app scope, or topic changes. When delegating, pass both IDs to the child agent or subprocess and require it to use them and return them unchanged with its answer. A new agent, subprocess, or tool invocation does not start a new user conversation. If a follow-up is missing its handle, recover it from the parent or previous tool results before starting the query. Never reuse a handle with another organization or unrelated user conversation. Set new_conversation=true only when the user explicitly requests a fresh conversation; omit conversation_id for that reset.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | A read-only advertising or creative-performance question for Segwise. Examples: Which hooks had the best ROAS on Meta last week?; Which creatives are showing fatigue?; Compare CPA and revenue across these apps.; What should we scale, pause, refresh, or test next? | |
| app_names | No | Optional app names to restrict the analysis. | |
| date_range | No | Optional inclusive date range. | |
| conversation_id | No | Conversation history handle for the original user's conversation and organization, including delegated work. Omit on the first query. For follow-ups copy the exact conversation_id from the parent or latest start or completed result into start_segwise_query, even after date range, app scope, or topic changes. Pass it and organization_id to any child agent or subprocess. If missing on a follow-up, recover it from the parent or prior results before calling. Never share handles between unrelated user conversations or organizations. | |
| organization_id | No | Exact organization_id returned by list_segwise_organizations. Optional only when the authenticated user has exactly one eligible organization. | |
| new_conversation | No | Set true only when the user explicitly requests a fresh Segwise conversation. A follow-up, changed date range, or new child agent or subprocess is not a reset. Omit conversation_id when true. |
| Name | Required | Description |
|---|---|---|
| job_id | Yes | Opaque handle for this query. Pass it unchanged to get_segwise_query until the query reaches a terminal status. |
| status | Yes | Running means execution is in progress. Continue polling the same job; it is not a failure or an empty result. |
| message | Yes | Guidance for continuing this running query. |
| next_action | Yes | Tool to call next with the same job_id. |
| conversation_id | Yes | Preserve this exact conversation handle for later queries in the original user's conversation and organization, including after a failed job. Pass it and organization_id unchanged between parent and child agents or subprocesses handling that conversation. |
| organization_id | Yes | |
| organization_name | Yes | |
| execution_deadline | Yes | Absolute RFC3339 execution deadline for this query. Polling does not extend it. This is not the result retention deadline. |
| poll_after_seconds | Yes | Minimum delay in seconds before the next get_segwise_query call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark this readOnlyHint=false and idempotentHint=false; the description explains why — it creates a persistent background job and may save conversation history — so the agent understands the side effects. It adds operational behavior the annotations cannot convey: multi-minute latency, many running status checks, retry guidance for transient vs auth errors, and explicit warnings not to start duplicate queries or abandon while polling remains available.
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?
Content is front-loaded with purpose first and mechanics later, which is good, but the body is roughly 350 words with heavy repetition around polling ("Keep calling get_segwise_query with the exact same job_id," "Do not start a duplicate query," and the restatement about running status) and repeated continuity language already present in the schema. The volume is defensible for a long-running job tool but could be trimmed meaningfully without losing information.
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?
Given a background-job tool with an output schema, no annotation coverage of async semantics, and a six-parameter surface, the description covers everything an agent needs: async lifecycle, terminal conditions, retry policy, delegation rules, and organization/conversation handle resolution. Nothing material to correct invocation appears to be missing.
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?
Schema coverage is 100%, so the baseline is 3; the description still adds meaning, notably the organization-name-to-ID resolution procedure ("present only organization names to the user, map the chosen name to the corresponding organization_id") and the cross-invocation continuity rules for conversation_id and organization_id. Some of this duplicates the schema parameter descriptions nearly verbatim, which slightly reduces the marginal value.
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 uses a specific verb and scope: "Analyze the authenticated organization's advertising and creative performance using Segwise's internal agent," and enumerates the dimensions (app, campaign, ad network, creative, tag) and metrics covered. It also explicitly names what it does not do ("cannot modify campaigns or generate creatives"), cleanly separating it from get_segwise_query, which it identifies as the polling counterpart.
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?
It explicitly routes the agent: use this to start analysis, then call get_segwise_query with the returned job_id until completed or failed, and stop only on the enumerated terminal states. It specifies organization_id selection behavior when multiple orgs exist and when to set new_conversation=true, and it names the excluded capability (no campaign mutation or creative generation).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_segwise_querylist_segwise_organizationsstart_segwise_queryRead-only Google Ads, Meta Ads and TikTok Ads performance, campaigns and creatives via OAuth.
Query warehoused Google Ads, Meta, GA4, Shopify, HubSpot and 85+ marketing sources in one place.
Query Meta Ads performance data — accounts, campaigns, ad sets, ads, metrics & settings.
Analyse ads and manage creatives across Meta, Google Ads, AppLovin, Unity, Mintegral and TikTok.
Add one secure layer between your agents and this server.
