Anonymous read-only access to settled advertising Spotlights, with an MCP Apps card.
Scored across 5 tools
The sandbox job tools (create_sandbox_job, get_sandbox_job) and real spotlight tools (list_spotlights, get_spotlight, get_current_spotlight) are clearly separated. However, get_current_spotlight and get_spotlight both retrieve a single spotlight and could be confused, though descriptions distinguish current vs. by-date.
All tool names follow a consistent snake_case verb_noun pattern: create_sandbox_job, get_sandbox_job, get_current_spotlight, get_spotlight, list_spotlights. The convention is predictable and readable.
Five tools are well-scoped for a public read-only spotlight API plus a sandbox idempotency exercise. Each tool has a clear, distinct role and none feels redundant.
The toolset covers listing, fetching by date, fetching the current spotlight, and the sandbox job lifecycle. Minor gaps exist (e.g., no search/filter or pagination control for list_spotlights), but core read and sandbox operations are covered.
Start a synthetic asynchronous sandbox job that exercises the Idempotency-Key and 202-then-poll pattern of the write API without touching real auctions, ads or money. Poll it with get_sandbox_job.
| Name | Required | Description | Default |
|---|---|---|---|
| idempotencyKey | Yes | Client-chosen key; the same key always returns the same jobId. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, readOnlyHint=false and destructiveHint=false, so the safety/idempotency profile is partly covered. The description adds genuinely new behavioral context: the job is asynchronous and follows a 202-then-poll lifecycle, and it has no side effects on real auctions, ads or money — the latter is important for a non-readOnly tool. It does not mention auth requirements or rate limits.
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?
A single sentence, front-loaded with the core action and scope, with the polling follow-up appended. No filler or repetition of the title.
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 values need not be explained; the description still covers the async 202-then-poll behavior and names the tool used to retrieve results. For a one-parameter sandbox tool this is fully sufficient.
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?
Only one parameter and schema description coverage is 100%, so the schema already fully documents idempotencyKey (client-chosen, same key returns same jobId). The description references the Idempotency-Key pattern but adds no syntax, format, or edge-case detail 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.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (start a synthetic asynchronous sandbox job) and immediately scopes it as exercising the Idempotency-Key / 202-then-poll pattern without touching real auctions, ads or money. It names the sibling get_sandbox_job as the polling counterpart, so an agent can distinguish it from siblings 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for use (synthetic job to exercise the write API's async idempotency pattern safely) and explicitly routes the follow-up action to get_sandbox_job. It stops short of stating exclusions, e.g. when a real (non-sandbox) job creation path would be preferred, but no such sibling exists here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the currently displayed settled public Spotlight, including labeled house advertisements. Does not bid or pay.
| Name | Required | Description | Default |
|---|---|---|---|
| includeHouseAds | No | When false, a current house advertisement is reported as unavailable instead of returned. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world. The description adds genuine behavioral context beyond that: the value is 'settled', it is 'public', it includes 'labeled house advertisements', and 'Does not bid or pay' clarifies this is a pure read with no financial side effect.
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?
Two short sentences, front-loaded with the core action and followed by a clarifying negative constraint. Both sentences earn their place, though the phrasing is slightly dense ('settled public Spotlight').
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 an output schema present, return values need not be explained, and rich annotations cover the safety profile. The description is essentially complete for a zero-required-parameter read tool, with only the sibling-selection guidance left implicit.
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 description coverage is 100%, so the single parameter includeHouseAds is already fully documented in the schema. The description's mention of 'including labeled house advertisements' gestures at the same concept but adds no syntax or behavior beyond what the schema states, so baseline 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 a precise verb and resource ('Read the currently displayed settled public Spotlight') and adds the scope qualifier 'current', which separates it from the sibling get_spotlight. It does not explicitly name the siblings it differs from, so it is clear but not fully differentiated.
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 only implied: 'currently displayed' suggests this is the live/active variant versus list_spotlights or get_spotlight, but the description never states when to choose this tool over those siblings. No explicit alternatives or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the status and synthetic result of a sandbox job created with create_sandbox_job. Every well-formed jobId resolves as completed, so a result is not proof that the key was created.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | jobId returned by create_sandbox_job. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds a non-obvious semantic caveat that structured data cannot express: every well-formed jobId resolves as completed, so a result is not evidence the key was created. That is exactly the kind of behavioral warning that prevents an agent from drawing a false conclusion.
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?
Two sentences, zero waste. The purpose is front-loaded and the validity caveat follows immediately after, in the order an agent needs it.
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 shape needn't be restated, and the description instead spends its space on the interpretive caveat that matters most. Nothing needed to call or correctly interpret this single-parameter read tool is 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% and the schema already documents jobId as 'returned by create_sandbox_job', including the format pattern. The description's mention of the jobId origin is essentially redundant, so the baseline 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?
States a specific verb (read) plus the exact resource (status and synthetic result of a sandbox job), and explicitly ties it to the sibling that produces the jobId. An agent can distinguish it from create_sandbox_job 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?
Names the prerequisite and originating sibling ('a sandbox job created with create_sandbox_job'), giving clear context for when this tool applies. It stops short of stating exclusions or alternative lookup paths, so it is not a full when/when-not statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one settled public Spotlight by date, including labeled house advertisements. Removed or missing days are unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| day | Yes | Settled auction date in UTC, YYYY-MM-DD. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real context beyond that: the response includes labeled house advertisements, and days that were removed or never existed are unavailable rather than returning empty data.
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?
Two short sentences, subject and selector front-loaded, with the availability caveat second. Nothing is padding, though the house-advertisement detail is a slightly tangential insertion.
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 an output schema present, return values need not be described, and the description covers scope, the date selector, and the failure mode. Complete enough for a one-parameter read tool, with only the sibling-routing guidance 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% and the single 'day' parameter is fully documented in-schema (UTC, YYYY-MM-DD). The description's 'by date' and 'settled' wording reinforces the schema but adds no format or semantics the agent does not already have.
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?
States a specific verb (read) and resource (one settled public Spotlight) plus the selector (by date), which cleanly separates it from get_current_spotlight and list_spotlights by implication. It stops short of naming those siblings, so the differentiation is inferential rather than explicit.
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 by 'settled ... by date' and the note that removed/missing days are unavailable, which tells the agent this is a historical, single-day lookup. However it never says when to prefer this over get_current_spotlight or list_spotlights, so the agent must infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse settled public Spotlights, newest first, including labeled house advertisements. Removed ads are excluded.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | Exclusive older-date cursor from nextCursor; cannot be combined with offset. | |
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description goes further by disclosing ordering (newest first), inclusion of labeled house advertisements, and exclusion of removed ads – genuine behavioral traits beyond the structured fields.
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?
A single tight sentence with zero filler, front-loading the resource and the two most decision-relevant facts (ordering and filtering). Every clause earns its place.
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 values need no explanation, and annotations cover the safety profile. The remaining gap is pagination semantics for limit/offset, which neither the description nor the schema documents.
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 description coverage is only 33%: cursor is documented in the schema, but limit and offset carry no description and the tool description adds no meaning for any of them. With a low coverage ratio, the description should compensate for pagination semantics but does not.
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?
States a specific verb ('Browse') and resource ('Spotlights') and adds scope: settled, public, newest first, house ads labeled, removed ads excluded. This clearly distinguishes it from the get_* siblings that return a single spotlight, though it never names them explicitly.
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?
The listing framing implies this is the tool for browsing multiple spotlights vs. get_spotlight/get_current_spotlight for single items, but there is no explicit when-to-use, when-not, or alternative naming. Usage is inferable but not stated.
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.
create_sandbox_jobget_sandbox_jobget_current_spotlight1 field changedInput schema / properties / includeHouseAdsAdded value: +{
+ "default": true,
+ "description": "When false, a current house advertisement is reported as unavailable instead of returned.",
+ "type": "boolean"
+}read_agent_docslist_spotlights3 fields changedInput schema / notAdded value: +{
+ "required": [
+ "cursor",
+ "offset"
+ ]
+}Input schema / properties / cursorAdded value: +{
+ "description": "Exclusive older-date cursor from nextCursor; cannot be combined with offset.",
+ "format": "date",
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+ "type": "string"
+}Output schema / anyOfPrevious value: -[
- {
- "properties": {
- "data": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "advertiser": {
- "type": "string"
- },
- "canonicalUrl": {
- "format": "uri",
- "type": "string"
- },
- "contentType": {
- "enum": [
- "paid_advertisement",
- "house_advertisement"
- ],
- "type": "string"
- },
- "day": {
- "description": "Settled auction date in UTC, YYYY-MM-DD.",
- "format": "date",
- "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
- "type": "string"
- },
- "description": {
- "type": "string"
- },
- "headline": {
- "type": "string"
- }
- },
- "required": [
- "day",
- "headline",
- "description",
- "advertiser",
- "canonicalUrl",
- "contentType"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "nextOffset": {
- "type": [
- "integer",
- "null"
- ]
- }
- },
- "required": [
- "data",
- "nextOffset"
- ],
- "type": "object"
- },
- {
- "properties": {
- "detail": {
- "type": "string"
- },
- "docs": {
- "format": "uri",
- "type": "string"
- },
- "status": {
- "type": "integer"
- },
- "title": {
- "type": "string"
- },
- "type": {
- "type": "string"
- }
- },
- "required": [
- "type",
- "title",
- "status",
- "detail"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "properties": {
+ "data": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "advertiser": {
+ "type": "string"
+ },
+ "canonicalUrl": {
+ "format": "uri",
+ "type": "string"
+ },
+ "contentType": {
+ "enum": [
+ "paid_advertisement",
+ "house_advertisement"
+ ],
+ "type": "string"
+ },
+ "day": {
+ "description": "Settled auction date in UTC, YYYY-MM-DD.",
+ "format": "date",
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "headline": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "day",
+ "headline",
+ "description",
+ "advertiser",
+ "canonicalUrl",
+ "contentType"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "nextCursor": {
+ "anyOf": [
+ {
+ "description": "Settled auction date in UTC, YYYY-MM-DD.",
+ "format": "date",
+ "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "nextOffset": {
+ "type": [
+ "integer",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "data",
+ "nextOffset",
+ "nextCursor"
+ ],
+ "type": "object"
+ },
+ {
+ "properties": {
+ "detail": {
+ "type": "string"
+ },
+ "docs": {
+ "format": "uri",
+ "type": "string"
+ },
+ "status": {
+ "type": "integer"
+ },
+ "title": {
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "title",
+ "status",
+ "detail"
+ ],
+ "type": "object"
+ }
+]get_current_spotlightget_spotlightlist_spotlightsread_agent_docsRead-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Anonymous, read-only cross-venue discovery of partner-approved venues, cities, destinations.
Anonymous read-only access to source-backed public SHAR Production knowledge.
Add one secure layer between your agents and this server.
