Brix Digital Signage

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

Goes well beyond the annotations: it discloses partial-failure semantics (out-of-reach ids are skipped and counted as `skipped`, never fatal), that existing membership is preserved, that no content/settings/location change, and the required permission. The annotations only carry the safety profile; the description supplies the rich behavioral detail.

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?

Front-loaded with the core action, then behavioral guarantees, then alternatives, then permission. Every sentence carries distinct information; there is no filler despite the density.

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 spelled out, yet the description still summarizes the return (count and ids). Combined with the safety annotations and full schema coverage, an agent has everything needed to call this correctly.

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 both groupId and screenIds are fully documented in the schema (including the sgrp_ prefix and the 1–5000 bound). The description adds the 'existing group' precondition but no new syntax or format detail, 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 ('Add screens to an existing screen group') with clear scope, and explicitly names the sibling operations it is not (create_screen_group, remove_screens_from_group, assign_screen_to_node). An agent can distinguish it from all three 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 explicit routing: create_screen_group for a new group, remove_screens_from_group to remove, assign_screen_to_node to move location. It also states the prerequisite permission ('Requires `screen.edit`'), 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.

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

Annotations declare destructive/idempotent/openWorld, but the description goes well beyond them: it discloses the required `screen.cast` permission, the lasting-vs-timed semantics, that screens are notified at once, and the partial-failure contract (skipped screens counted as notShared/needsApproval instead of failing the call). That partial-success behavior is the kind of thing an agent genuinely needs and cannot get from 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?

One dense paragraph, front-loaded with the core distinction before targeting modes and failure semantics. Every clause carries information, though the mid-paragraph switch between targeting, notification, and error handling makes it slightly harder to scan than a short bulleted split would be.

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 spelled out, and the description still notes that the response names changed screens. With permissions, failure modes, targeting, and the clearing path all covered, nothing needed 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.

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: nodeId is illustrated with a concrete use case ('all California stores' in one call), the combination rule between screenIds and nodeId is restated at the tool level, and the null-clears-one-screen constraint is called out with its single-screen limitation. It does not, however, explain contentId/contentKind pairing beyond what the schema says.

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 and resource ('Change what screens play by default') and immediately scopes it as a lasting assignment rather than a timed takeover, which is exactly the axis that separates it from cast_content. An agent can distinguish it from all siblings without opening a 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?

Explicitly routes: 'Use cast_content for a temporary takeover that ends by itself, quick_post to write and show a new message.' It also states when it applies (default, lasting, until changed) and enumerates the three targeting modes plus their combination rule.

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

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

Goes well beyond the annotations. It discloses what actually changes (permissions, approval rules, inherited timezone) versus what does not (content), the two refusal conditions (content needing approval at destination, account on hold moving into a paying location), and the required scope (`screen.edit` at both old and new location). The destructive/idempotent annotation hints are consistent with 'single home in the tree.'

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?

Front-loads the core action and consequence in the first sentence, then layers refusal conditions, usage scenarios, alternatives, and permissions. Dense and mostly waste-free, though the accumulation of clauses makes it longer than strictly necessary.

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 no explanation, and the description already covers prerequisites, side effects, refusal cases, and alternative tools. 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.

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to nodeId by explaining that the destination governs manage rights, approval rules, and timezone inheritance. It does not add syntax beyond the schema, so it stays shy of a 5.

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 and resource ('Move one screen to a different location (org node)') and immediately distinguishes it from the nearest sibling by noting this is the screen's 'single home in the tree.' An agent can tell it apart from add_screens_to_group and bulk_create without opening a 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?

Explicitly routes the agent: use add_screens_to_group for a flat label that changes no permissions, and bulk_create to create the location first. It also names the scenario ('post-migration cleanup'), so when-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but the description adds far more: per-kind permission scopes (playlist.create, schedule.create, org-unit.create, integration.create), idempotency for locations ('a node whose externalId already exists is skipped, so re-running is safe'), and partial-failure semantics for celebrations ('one bad row is reported, not fatal'). It also clarifies that item refs must already exist, which is a real prerequisite not visible in 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?

A single dense paragraph, but it is front-loaded with the core verb and the 'exactly ONE of' rule before enumerating kinds, and each clause carries non-obvious information (limits, permissions, idempotency). The one nit is that the paragraph is long and scannable structure (per-kind bullets) would help an agent parse four variants quickly.

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 shapes need not be described, and the description still covers everything else an agent needs: which arrays are mutually exclusive, size caps, required pre-existing references, permission scopes, per-kind error behaviour, and where to go for related write operations. Nothing material is left to inference for a four-variant bulk write tool.

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, but the description adds genuine meaning beyond the schema: the mutual exclusivity of the four arrays ('exactly ONE of') is not expressible in the schema, and it specifies that schedule block times are 'HH:MM 24-hour in the SCREEN's timezone', a detail the schema omits. It also reiterates the per-kind caps and parentExternalId ordering, which the schema also covers, so it is additive rather than redundant.

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 and resource ('Create many records of one kind in one call') and then enumerates the four record kinds it accepts with their individual semantics. It also names the sibling it is not — update_playlist and create_creatives — so an agent can distinguish it from neighbouring write tools 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?

Explicitly frames itself as 'the migration and import tool' and states the cardinal rule 'Pass exactly ONE of' followed by per-kind conditions. It closes with an explicit exclusion and routing ('Only creates; to change an existing playlist use update_playlist, to design a screen use create_creatives'), giving both when-to-use and when-to-use-something-else.

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

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

Discloses behavior well beyond the annotations: it sends a command, waits ~5s for a new frame, defines the `fresh` flag semantics, and specifies fallbacks for slow/offline screens (last stored frame, fresh:false) and oversized frames (>2 MB no inline image). It also states the required `screen.edit` permission. This is consistent with readOnlyHint=false, since a command is dispatched to the player.

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?

Front-loaded with the action and its output, then progressively layers timeout, return fields, and fallbacks. Dense but every sentence carries distinct operational information; the return-field enumeration is slightly redundant given an output schema exists.

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?

Covers everything an agent needs: the permission requirement, the wait/timeout, the freshness semantics, and the degraded-path behavior for offline or oversized frames. An output schema exists, so the additional return-field detail is bonus rather than a gap.

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% and the schema already documents screenId with an example and a pointer to search_screens. The description only adds the constraint 'One screen per call,' which the schema already implies via a single required screenId, 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?

States a specific verb and resource ('Take a screenshot of one screen now and return it as an image') with explicit scope ('one screen'). It also distinguishes its role from the diagnostic sibling by directing agents to screen_health for 'WHY' questions.

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 a clear purpose ('to check what is actually on the panel') and names screen_health as the alternative for a related-but-different question. It does not, however, address when to use this versus other screen-state siblings like refresh_screen.

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

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

Annotations declare destructiveHint=true and idempotentHint=true but say nothing about reversibility or auth. The description adds that screens revert to their normal schedule on expiry, that it returns a castId routable to end_cast, and that it requires `screen.cast`. That is substantive context beyond the structured fields, and it does not contradict the destructive flag.

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?

Front-loaded with the core behavior, then scope, then the canonical example, then alternatives, then the return/permission notes. Every sentence carries distinct information with no filler.

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?

Covers purpose, scope options, reversibility, the stop-early path via end_cast, the permission requirement, and sibling routing. With an output schema present, it does not need to detail return shape, and it still surfaces the castId handoff that matters operationally.

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 adds real value by explaining the scope axis ('everything (all), an org node subtree, or explicit screenIds') and reinforcing that contentId must reference EXISTING content, mapping the two enum parameters to intent rather than just restating them.

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+behavior: 'Show EXISTING content on screens as a TIMED takeover (a cast)'. It explicitly distinguishes itself from siblings assign_content, quick_post, and trigger_emergency_template, so an agent can route correctly without opening schemas.

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 a concrete usage scenario ('put the lunch menu on the lobby screens until 2pm') and explicit alternatives with selection conditions: assign_content for a lasting change, quick_post to write new content, trigger_emergency_template for emergencies. Nothing is left to inference.

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

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

Annotations declare the safety profile (destructive, idempotent, openWorld, not readOnly), but the description adds what they cannot: the visible side effect that media may show late or blank during re-download, that bulk calls silently skip screens outside your reach, and the required `screen.edit` permission. That is exactly the extra context annotations cannot carry.

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 short sentences, front-loaded with the action and effect, then the when-to-use, then the alternative, then the permission requirement. 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?

Covers the mutation, its user-visible consequence, the fallback tool, bulk behavior, and the auth scope; an output schema exists so return values need no explanation. 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.

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 goes beyond it by explaining the relationship between screenId and the bulk screenIds path and that out-of-reach screens in a bulk call are skipped rather than erroring. It stops short of restating the 200-item cap, which lives in the schema.

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 and resource ('Delete the content files stored on one screen or many') plus the downstream effect ('so the player downloads them again'), which is exactly the distinction an agent needs. It also implicitly separates itself from refresh_screen by contrast later in the text.

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 ('when a screen plays an old or damaged file') and an explicit preferred alternative with the reason it should be tried first ('try refresh_screen first, which keeps the stored files'). This is a textbook when/when-not/alternative statement.

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

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

Annotations already mark this as a non-read-only, idempotent, non-destructive, open-world mutation, but the description adds real behavioral context beyond them: partial-update semantics ('Only the fields you pass are changed'), the side effect that showOnly silently switches the link to snapshot rendering with a 300 s default refresh, the refusal case, and the `media.edit` permission requirement.

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?

Dense and front-loaded: capabilities first, then the showOnly caveat, then side effects, then alternatives and permissions. Almost every sentence carries actionable information, though the run is long enough that the snapshot/refresh side effect could be tightened into a shorter clause.

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 6-parameter mutation tool with an output schema, everything an agent needs is present: partial-update behavior, the snapshot-rendering side effect and its default refresh, the media-type restriction, the required scope, and pointers to the preview and rename siblings. Return values are rightly 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: showOnly takes a CSS selector, empty string restores the full page, and ids should be preferred over class names because republishing changes classes. It does not add anything beyond the schema for renderWidth/renderHeight/refreshSeconds/autoScrollPxPerSec.

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?

Specific verb (change how a web link renders) plus an enumeration of the exact renderable aspects (cropping, auto-scroll, refresh cadence, viewport size). It also names the siblings it is not — render_web_link for previewing and update_media for name/tags/folder — so an agent can disambiguate without opening the schemas.

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 explicit routing: 'Then use render_web_link to see the result now; for name, tags or folder use update_media.' It also states the precondition that cropping requires a server-rendered snapshot and that the tool is refused for non-web-link media, so the when/when-not conditions are fully covered.

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

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

Goes well beyond the annotations (which only declare non-read-only, non-destructive, closed-world) by disclosing server-side validation/clamping, whole-call rejection on an invalid box, a 100-creative cap, and the full quality-gate behavior including specific REJECT and WARN conditions. This is exactly the operational context an agent needs before invoking.

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?

Purpose and alternatives are front-loaded and almost every sentence carries information, but the box-kind documentation is delivered as one dense run-on paragraph rather than clearly delimited, which slows parsing for a payload this complex.

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 complex write tool with an output schema already present, the description covers creation semantics, validation/failure modes, the quality gate, limits, and the follow-up tooling to make the design visible. Nothing necessary for correct invocation 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%, but the description adds meaning the schema does not: the per-kind extra fields for text, field, list, image, shape, signage, and slot layers, plus the 0–1 fractional coordinate semantics and the 'slot:null = empty hole' convention. It substantially exceeds the schema on the most consequential nested payload.

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 and resource ('Author new creatives (data-bound canvases) from scratch') and frames the tool's role as the programmatic template-building path. It explicitly distinguishes itself from assign_content, cast_content, and quick_post, so an agent can route without opening a 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 explicit when-to-use ('This is how you BUILD templates programmatically') and what happens after ('Creating a design shows it nowhere; put it on screens with assign_content or cast_content'). It also names a direct alternative with its triggering condition ('For a one-off text announcement use quick_post').

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

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

Beyond the annotations (which only say it is a non-read-only, non-destructive, closed-world write), the description discloses the duplicate-name refusal, that out-of-scope screenIds are skipped silently, that groups carry no permissions, and the required `screen.edit` permission.

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?

Front-loaded with the definition of the resource before mechanics and routing. Dense but each clause (uniqueness, permission, cross-location semantics) carries distinct information; only slightly long for a single-create tool.

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. The description covers authorization, failure mode, member-add semantics, and sibling routing, leaving no obvious gap for an agent to call this correctly.

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 name, screenIds and description are already fully documented. The description only restates that members are optional via screenIds; it adds no format, limit or interaction 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 and resource ('Create a named screen group') and immediately defines what the resource is ('a saved set of screens you handle together'). The clarification that a group is a flat label that grants no permissions distinguishes it from location-tree or permission constructs.

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?

Explicitly routes the agent: add members later with add_screens_to_group, and use assign_screen_to_node to change where a screen lives. It also states the precondition that creation is refused on a duplicate name, so the agent knows when this call will fail.

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

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

Annotations already declare the write, non-idempotent, open-world nature, but the description adds substantial non-obvious behavior: it returns a new mediaId, requires media.create, refuses private/loopback addresses unless onScreenNetwork is set, and explains that on-screen-network URLs are stored but never fetched by the cloud. This is rich behavioral context beyond structured 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?

The description is front-loaded with the core action, then branches into return value, special parameter behavior, alternative tool, and permission requirement. Every sentence carries distinct, useful information with no filler.

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 detailed, but the description still highlights the important mediaId. It covers purpose, alternatives, sequencing, permission requirements, and the one non-obvious parameter behavior, making it complete for an agent to invoke correctly.

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 meaningfully supplements the schema for the critical onScreenNetwork parameter — explaining what setting it true actually does — and clarifies the URL restriction for private/loopback addresses, though it adds little beyond the schema for name, tags, or folderId.

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 specific verb and resource — adding a web page or dashboard to the media library — and immediately distinguishes this from sibling tools like configure_web_link and upload_media_from_url. An agent can tell what the tool creates and where it belongs without opening the 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 explicitly names the alternative for a different use case (upload_media_from_url for copying files), gives the follow-up step (pass mediaId to configure_web_link), and states the condition for the special onScreenNetwork path. Nothing about when to use this tool versus alternatives is left to inference.

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

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

Annotations already cover the safety profile (destructiveHint true, readOnlyHint false), and the description adds real value beyond them: the concrete effect of each decision (content airs vs stays off screens), the requirement of a reason for reject, and the authorization constraint that causes refusal. It does not address reversibility or rate limits, but the added auth and effect disclosure is substantive.

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?

Front-loaded with the action and appropriately sized for a mutation with authorization constraints. There is minor redundancy in referencing list_pending_approvals both parenthetically up front and again in the final sentence.

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?

Output schema exists, so return values need not be explained, and the description covers the key gaps an agent needs: decision effects, the reason requirement, and the approver-identity precondition. Complete enough to invoke correctly, with only minor omissions around post-decision state.

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 schema already documents approvalId, decision (with enum), and the conditional reason requirement. The description's note that rejecting 'needs a reason' reinforces but does not meaningfully extend what the schema states, so baseline 3 is appropriate.

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 pair (approve/reject) and a specific resource (one pending approval request), and explicitly ties the request to the list_pending_approvals sibling as its source. An agent can distinguish it from list_pending_approvals 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?

Clearly states the prerequisite condition — the connection identity must be an approver for the request's chain, otherwise the call is refused — and points to list_pending_approvals for discovery. It lacks an explicit 'do not use this instead of X' exclusion, but the when-to-use context is strong.

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

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

Annotations already declare destructive=true and idempotent=true. The description still adds real context beyond them: the concrete effect (screens revert to scheduled content immediately) and an explicit authorization requirement (screen.cast), which annotations do not convey. It stops short of covering failure modes or partial-success semantics, so it is not a 5.

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?

Three dense sentences, front-loaded with the action and scope. The per-screen warning and the auth requirement are parenthetical and each earn their place with no filler.

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. For a single-parameter mutation the agent gets the effect, the permission needed, the idempotency behavior, and the correct identifier source — nothing material 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 description coverage is 100%, so a 3 is the baseline. The description goes further by stating the parameter accepts either the returned castId or the creativeId/contentId of the content being cast, and by clarifying that one cast covers all its screens — semantics that help the agent supply the right 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?

States a specific verb+resource (end a cast) and immediately scopes it: it ends the cast on EVERY screen it covers, and the covered screens go back to scheduled content. This distinguishes it from siblings like cast_content/quick_post, which create casts rather than terminate them.

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?

Explicitly tells the agent where the castId comes from (quick_post or cast_content), warns against the common wrong pattern (do not call once per screen), and notes that ending an already-ended cast succeeds. These are concrete when/how-to-invoke instructions, not inference.

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

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

Beyond the readOnly/non-destructive annotations, it discloses the polling requirement, the visibility scoping rule that makes out-of-location runs appear missing, and the trap that frameKey records a proof frame rather than a fetchable URL. These are exactly the behaviors an agent would otherwise get wrong.

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?

Front-loaded with the core action, then four tight sentences covering polling, the frameKey caveat, the alternative tool, and the scoping rule. No sentence is filler.

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 unnecessary, annotations cover the safety profile, and the description supplies the remaining operational context (poll loop, scoping, caveats). Nothing needed to invoke it correctly 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 runId as the '(dtr_…)' value returned by start_device_test_run, so the description adds no syntax or format detail beyond it. Baseline 3 for a fully documented single parameter.

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 and resource ('Read a Device Lab run that start_device_test_run queued') and enumerates the returned payload (status, suite, device, summary, per-step pass/fail, expected vs observed, time taken). It clearly differentiates itself from start_device_test_run (the producer) and capture_device_frame (the screenshot path).

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?

Explicitly instructs to poll until the run has finished, routes screenshot needs to capture_device_frame, and explains the cross-location failure mode ('reads as not found'). Both when-to-use and the alternative path are stated outright.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value on top by naming the required scope (`playlist.view`) and itemizing the returned structure, including the item id that update_playlist consumes. It does not discuss pagination or limits on very large playlists, which keeps it short of a 5.

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, front-loaded with what is returned, then routing and permission. Every clause carries information; nothing is restated from the schema 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 single-parameter read tool with an output schema, an output schema already documents the return shape, and annotations cover safety. Adding the permission requirement and id provenance makes the definition fully sufficient for correct invocation.

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, but the description adds meaning beyond the schema by tying playlistId provenance to list_items (kind playlists) and clarifying that the returned item ids are what update_playlist needs. That cross-tool semantics for identifiers is genuine added 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?

States a specific verb and resource ('Read one playlist') and enumerates exactly what comes back: name, items in play order, item ids, content, duration, approvalState, shuffle. It is immediately distinguishable from siblings such as list_items, update_playlist, and get_proof_of_play.

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 explicit routing: use list_items (kind playlists) to find ids, use update_playlist to change the playlist, and states the required `playlist.view` permission. Both the 'when to use' and the 'use this instead' alternatives are named.

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

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

Annotations already declare readOnly/non-destructive/openWorld=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: results are scoped to 'screens in locations you can see' and calling requires the `playback-log.view` permission. It does not mention pagination or result-size behavior, keeping it just short of a 5.

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?

Tight and front-loaded: the core output description comes first, then the disambiguating siblings, then the permission. Every sentence earns its place with no filler.

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 format needn't be restated, and annotations cover safety. The description still supplies the scoping rule, permission prerequisite, and sibling disambiguation, making it complete for an agent to call correctly.

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%, with ISO-datetime defaults documented for to/from and the screenId restriction explained inline, so the schema carries the burden. The description's 'time window' phrasing adds only modest semantic framing over that baseline.

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 report verb and resource ('proof-of-play rollup for a time window') and enumerates its contents (plays, watch time, skips, failures per piece of content, reporting screens). The framing question 'how did the promo actually do?' further pins the intent, and it is clearly distinct from uptime and audit siblings.

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?

Explicitly routes to alternatives with the selecting condition: get_uptime_report for whether screens were online and search_audit_log for who changed content. It also states the data-scope constraint and the required permission, 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description goes well beyond that by disclosing the visibility scope, the deletion exclusion, the input validation rule ('a from/to that is not ISO 8601 is refused'), and the required permission. It also describes the per-entity outageSummary content an agent will receive.

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?

Front-loaded with the core purpose and result shape, then scope, then validation, then sibling routing, then permissions. Dense but every sentence carries distinct information with no filler.

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?

Despite an output schema existing (so return details are not strictly required), the description still explains the outageSummary structure and insight format, and covers scope, auth, validation, and alternatives. Nothing an agent needs to call it correctly 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%, so the three params with their defaults are already documented, making 3 the baseline. The description adds genuine meaning beyond the schema by specifying the ISO 8601 validation behavior and the default window semantics (30 days unless the workspace changed it), though it does not restate per-param syntax.

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 ('Uptime/SLA summary for a time window') and immediately enumerates the output shape: online % per screen, downtime windows with causes, worst offenders first. It is unmistakable against siblings like screen_health and get_proof_of_play, which it names directly.

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?

Routes the agent with explicit alternatives and the condition that selects each: 'screen_health (view outages) for one screen's outage list, list_open_alerts for what is wrong right now, get_proof_of_play for what actually played.' It also states scope ('screens in locations you can see; deleted screens are left out') and the required scope 'screen.view'.

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

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

Goes beyond the readOnlyHint annotation by disclosing the visibility constraint (templates homed outside your locations are hidden) and the required permission scope `emergency-override.view`. The 'Read-only' restatement is redundant with annotations, but the auth and scoping details are genuinely additive.

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?

Three tightly packed sentences with the resource, the downstream handoff, the scope caveat, and the permission requirement front-loaded. No filler and no repetition of structured data.

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 shapes need not be documented, and the description still names the key fields (ids, scope, severity). Between the permission requirement, visibility scope, and the id-handoff warning, an agent has everything needed to call this correctly.

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 schema carries no per-parameter burden and the baseline is 4. The description's mention of 'Pass an id' refers to the sibling trigger tool rather than an input here, which could momentarily confuse but harms nothing.

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 and resource ('List the pre-armed emergency takeover templates') and disambiguates with concrete examples (Lockdown, Severe weather, Fire drill). It also names the fields returned (ids, scope, severity) and distinguishes itself from the write-side sibling trigger_emergency_template.

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?

Explicitly routes the agent to trigger_emergency_template and warns 'never guess' an id, implying this list must be consulted first. It also states a scope condition (templates homed outside your locations are not shown). It stops short of an explicit when-to-use/when-not-to-use statement but the downstream routing is clear.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description goes well beyond them: page size (100), that the response carries total/hasMore, that rows are a short projection never full configs/members/billing, and that each kind is gated by its own view permission and errors if unreadable. That last point is operationally critical and cannot be derived 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?

Four sentences, each with a distinct job: purpose and kinds, filtering/paging mechanics, return shape, then sibling routing. Nothing is repeated and the selection-critical content is front-loaded.

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 further explanation, yet the description still flags the projection boundary (no members or billing) that an agent would otherwise have to guess at. Combined with the permission-error behavior, nothing needed to invoke this correctly 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%, so the baseline is 3, but the description adds real meaning beyond it: offset is quantified as '100 a page' with total/hasMore in the response, and the kind parameter is tied to the per-kind permission model. The q parameter's case-insensitive substring match is only restated from the schema, which keeps this below 5.

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 gives a specific verb and resource ('List one kind of item in this workspace') and enumerates the nine kinds inline, so an agent knows exactly what the tool returns without opening the schema. It also states the instrumentation-level purpose ('to pick an id for another tool'), which distinguishes it from read-for-display siblings.

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 routing: 'For media files use search_media; for screens use search_screens; for one playlist's items use get_playlist.' Combined with the positive 'to pick an id for another tool' framing, an agent can decide between this tool and its nearest siblings without inference.

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

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

Annotations cover the safety profile, and the description goes further by disclosing result ordering (newest first), page size (200), the response's pagination contract (total, hasMore, nextOffset), and an authorization constraint ('only alerts in locations this connection can see'). That permission-scoping 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?

Three tight sentences: capability and scope first, paging/filtering second, sibling routing last. No sentence is redundant and the most decision-relevant information is front-loaded.

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. The description covers filtering, ordering, pagination, visibility constraints, and alternative tools, so an agent has everything needed to select and invoke it correctly.

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 all four parameters are already documented in the schema, including the node vs. screen distinction and the offset default. The description only summarizes filters already present ('severity, one screen or one location') and adds no syntax or format detail, 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 a specific verb and resource with scope qualifiers: 'List alerts that are open now (not yet closed), newest first, 200 per page.' It explicitly differentiates itself from siblings by naming screen_health, get_uptime_report, and search_screens for adjacent needs.

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 gives an explicit when-to-use ('what is wrong right now') and three named alternatives with the exact condition that selects each, 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the workflow note that content created or edited over this connection lands as draft when its location requires approval, which explains why items appear here. It does not discuss pagination behavior, keeping it short of a 5.

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?

Three sentences, front-loaded with purpose and scope, then the default, then the sibling handoff. No sentence is redundant and nothing is buried.

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 two-parameter read-only list tool with an output schema present, the description covers purpose, defaults, filter semantics, the underlying workflow that generates pending items, and the handoff to decide_approval. Nothing an agent needs to select and call it correctly 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%, so both parameters are already documented, including the 'withdrawn' enum meaning. The description still adds value by framing the state parameter in workflow terms ('see decided history') and restating the pending default, which clarifies intent beyond the raw enum.

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 specific verb+resource ('List approval requests') and immediately scopes it to 'content waiting for an approve/reject decision before it can air.' This clearly separates it from the sibling decide_approval, which acts on a single item rather than listing them.

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 states the default behavior ('Defaults to pending'), the alternative state filter ('pass state to see decided history'), and the routing rule to the sibling mutation tool ('to approve or reject one, pass its id to decide_approval'). When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations already declare the safe read-only, non-destructive profile, but the description adds real operational context beyond them: the 30-day restore window, newest-deletion-first ordering, default page size of 50, and that soft-deleted screens are included. The closing 'Read-only' merely repeats the annotation, and it does not cover auth or pagination mechanics beyond the default, so it stops short of a 5.

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 purpose and scope are front-loaded, then paging, filtering, restore routing, and the screen inclusion note follow logically. Every sentence serves a purpose except the redundant 'Read-only,' which duplicates the annotation.

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 safety is covered by annotations. The description supplies the remaining essentials: scope, retention window, ordering, paging, filtering, and the sibling handoff for restoration.

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 schema fully documents q, kind, limit, and offset; baseline is 3. The description explains the intent of filtering ('to find one item') but adds no parameter syntax, format, or constraints beyond what the schema already provides.

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 and resource ('List soft-deleted items') and scopes it to every content kind within the 30-day restore window. It distinguishes itself from the sibling restore_recycle_bin_item by naming it explicitly and explaining the handoff. An agent can identify the operation and its boundary 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?

Directly routes the agent: use this tool to list and filter, and pass a row's kind and id to restore_recycle_bin_item for undo requests. It also states how to find a single item via the kind or name filters. The when-to-use and the alternative are both explicit.

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

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

Annotations declare destructive/openWorld write semantics, and the description goes beyond them with transactional behavior: no screens reached means nothing is created, a failed cast removes the creative, the post auto-expires after expiresInSec, and it requires `creative.create` and `screen.cast`. That is meaningful context an agent cannot get from the annotations alone.

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?

Front-loads the one-step atomic behavior, then stacks behavior, return value, alternatives, and permissions in dense but non-redundant sentences. Slightly packed, but no sentence is filler.

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?

Despite an output schema existing, the description still explains the one return value that matters operationally (castId feeding end_cast). For a 7-parameter mutation with rollback semantics, nothing an agent needs to invoke it correctly 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 description coverage is 100%, so every parameter is already documented in the schema (including enum meanings and cross-references to search_screens/list_items). The description reinforces the headline+body+tone composition and the expiresInSec lifespan but adds no new syntax or constraints. 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 ('Write a short text announcement and show it on screens in ONE step') and explicitly positions itself against siblings ('Use cast_content to show content that already exists, trigger_emergency_template for an emergency'). An agent can pick it apart from cast_content without opening the 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 explicit when-to-use routing to two named alternatives and states the selection condition for each (existing content vs. emergency). It also covers the follow-up case: pass castId to end_cast to take the post down early.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds context annotations cannot convey: the screen goes blank until the player restarts (typically under a minute), screens outside your reach are silently skipped in bulk calls, and the `screen.edit` permission is required. This is exactly the operational context an agent needs before invoking a disruptive restart.

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 short sentences, each earning its place: capability, impact/duration, usage routing, partial-failure behavior, and auth requirement. The core action is front-loaded before the caveats.

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. Combined with the downtime estimate, permission requirement, and bulk-skip semantics, the description covers everything an agent needs to invoke this disruptive tool safely.

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 both parameters (screenId, screenIds) and their formats are already documented in the schema. The description references the bulk form but adds no syntax or format detail beyond what the schema provides, 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?

States a specific verb and resource ('Restart the player on one screen or many') with the scope of the bulk variant. It explicitly differentiates itself from the sibling refresh_screen, so an agent can route correctly 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?

Gives a clear trigger ('when a screen is frozen or shows an error') and names the alternative with the condition that selects it ('when content is only out of date, refresh_screen is gentler'). This is explicit when-to-use and when-to-use-something-else guidance.

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

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true), the description discloses failure semantics ('one failing feed does not stop the rest'), a rate limit (5 calls a minute), and the required permission scope ('integration.edit'). These are operationally critical traits no structured field conveys.

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?

Three tight sentences, front-loaded with the core scope, then failure/limit behavior, then usage guidance. Every clause carries distinct information with no filler.

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?

Although an output schema exists, the description supplies the remaining operational context an agent needs: failure isolation, rate limiting, permission requirement, and sibling routing. Nothing essential is missing for correct invocation.

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 per the rubric the baseline is 4. The description adds nothing parameter-related, which is appropriate since there is nothing 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 states a specific verb (sync) and resource (EVERY connected data feed in this workspace) with an explicit scope qualifier ('that you can edit'). It cleanly distinguishes itself from the sibling sync_data_source by name, so an agent can select correctly 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 gives a concrete when-to-use ('before big announcements so menus/prices are current') and an explicit alternative with its selecting condition ('for one feed use sync_data_source'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: no restart is required, unauthorized screens are silently skipped in bulk, and the `screen.edit` permission is required. It stops short of describing latency/return behavior, which keeps it at a 4 rather than 5.

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?

Three tight sentences, front-loaded with the action and the primary routing guidance (the alternatives) immediately after. Every sentence carries decision-relevant information with no filler.

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. Permission requirements, alternatives, and bulk-skip semantics are all covered, giving the agent everything needed to call this correctly.

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% — both screenId (from search_screens) and screenIds (bulk, max 200) are fully documented in the schema. The description only restates the single-vs-bulk split without adding syntax or format detail, 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 concrete verb and resource ('Make one screen or many download and play their current content again, without a restart') and scopes it precisely. An agent can distinguish it from reboot_screen and clear_screen_cache from the description alone, 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?

Gives explicit when-to-use ('after a change that has not appeared on the screen yet') and names two alternatives with their selecting conditions: reboot_screen for a frozen player, clear_screen_cache for a stuck/broken file. It also discloses bulk-call scoping (screens outside your reach are skipped), 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.

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

Goes well beyond the annotations: it clarifies that despite destructiveHint=true nothing is deleted (content and location untouched, group persists even when empty), discloses permission requirements, and explains edge-case handling (skipped ids counted, non-member ids ignored). This is exactly the kind of nuance annotations cannot convey.

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?

Front-loads the core action and the key clarification (label-only removal) in one dense sentence, then adds routing and permission in a second. Every clause earns its place, though the long parenthetical chain makes it slightly heavy to parse.

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?

Covers purpose, the alternative tool, permission requirement, and id edge cases for a two-param mutation with full schema coverage and an output schema that handles return values. The only missing element is any mention of scale/rate considerations for the 5000-id upper bound.

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 both parameters are already documented with id prefixes and list/range constraints; the description adds only the `skipped` outcome vocabulary. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('take screens out of a screen group') and immediately disambiguates the scope of the mutation: only the label drops, the screens and their location remain. It also names the inverse sibling (add_screens_to_group), so an agent can pick between the two without inspecting schemas.

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 explicit routing to the alternative ('To add screens use add_screens_to_group') and states the required permission (`screen.edit`), plus how out-of-reach and non-member ids are handled. It lacks an explicit 'do not use this when...' clause, which is the only gap.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true. The description adds value beyond them: it clarifies that despite being a non-read operation it 'changes no settings', that it requires the `media.edit` permission, and that it only applies to snapshot-rendered links. It does not discuss cost/rate limits of forcing a render, so it stops short of a 5.

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 short sentences, front-loaded with what the tool does, followed by when to use it, its applicability constraint, and the permission requirement. No sentence is redundant or restates 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?

With an output schema present, return values need no explanation, and the description covers the remaining gaps: trigger timing, applicability limits, side-effect profile and required permission. Nothing an agent needs to invoke it correctly 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 description coverage is 100% for the single mediaId parameter, and the schema already documents its format (med_…) and provenance (create_web_link / search_media). The description adds no parameter-level meaning beyond that, 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?

The description states a specific verb and resource — forcing a fresh server-side snapshot of a web link — and immediately distinguishes itself from siblings by noting it changes no settings and that configure_web_link is the tool for changing crop/scroll. An agent can tell it apart from configure_web_link or refresh_screen 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?

It gives an explicit trigger ('right after configure_web_link to see whether a crop selector actually matched'), an explicit exclusion ('only meaningful for snapshot-rendered links — a live page is loaded by the screen itself'), and names the alternative for the mutation case (configure_web_link). When-to-use, when-not-to-use and the alternative are all present.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, but the description adds real behavioral context beyond them: referencing playlists/screens resume automatically, per-kind permission requirements (e.g. playlist.delete), and that purging is out of scope. It stops short of noting irreversibility or failure modes, so a 4 rather than 5.

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?

Front-loads verb and scope efficiently, and every sentence carries useful information about side effects, permissions, and exclusions. Slight redundancy from referencing list_recycle_bin twice (for kind and again at the end) prevents a full 5.

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?

Output schema exists so return values need no explanation; annotations cover safety, and the description supplies prerequisite, permission model, side effects, and exclusions. Nothing needed to invoke it correctly 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 description coverage is 100% and both params (id, kind with an enum) are documented in the schema, so baseline 3 applies. The description only echoes that kind/id come from list_recycle_bin, adding no new syntax or format detail.

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 (Restore) plus resource (soft-deleted recycle bin item) and scope (ONE), and explicitly ties the kind to list_recycle_bin, distinguishing it from that sibling and from purge operations. An agent can identify the action without opening schemas.

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 an explicit prerequisite/alternative path ('Find the kind and id with list_recycle_bin first') and a clear exclusion ('Purging (permanent deletion) is not part of this tool'), so both when-to-use and when-not-to-use are covered.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), yet the description adds substantial extra context: the required `screen.view` permission, the hard limitation that the player cannot read TV/HDMI state (so a 'guided' checklist is a guess, not a detection), that only CEC-connected Signage Sticks produce `tv` rows, and that planned darkness is listed but excluded from counts. That is exactly the kind of caveat an agent needs before trusting output.

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?

Front-loaded with the core purpose and the routing alternatives before the per-view detail. It is dense and long, but for a four-mode tool nearly every clause carries distinct information; a small amount of repetition between the view prose and the schema notes is the only waste.

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?

Output schema exists, so return shapes need not be re-explained, and the description instead supplies everything else an agent needs: view semantics, defaults/caps, detection limits, permission requirement, and sibling routing. Complete for a read-only diagnostic tool of this complexity.

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, and the schema already documents defaults and caps for `days` and `limit`. The description goes beyond that by explaining what each `view` enum value actually returns, giving the enum semantic weight the terse schema note ('see the tool description') deliberately defers.

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 and resource ('Read one screen's health') and then enumerates the four modes of reading via `view`, each with a distinct purpose. It explicitly distinguishes itself from the sibling tools an agent might otherwise pick (get_uptime_report, list_open_alerts, capture_device_frame).

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 per-view when-to-use guidance ('diagnose': for a screen that looks blank or wrong) and names three concrete alternatives with the condition that selects each: fleet/time window -> get_uptime_report, fleet-wide problems now -> list_open_alerts, live picture -> capture_device_frame. Nothing about routing is left to inference.

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

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

Beyond the readOnly/destructive annotations, the description discloses what is redacted (no emails, IP addresses, browser details), that MCP-tool-initiated changes are included, the newest-first ordering, keyset paging, and the `audit-log.view` permission requirement. That is substantive behavioral 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?

Three tight clauses with no filler; the core purpose leads, then paging mechanics, then the sibling disambiguation, then the permission gate. Every sentence carries load.

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, and the description still covers ordering, paging, redaction, permission, and alternative routing. Nothing an agent needs to invoke this correctly 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 description coverage is 100%, so limit/since/cursor are already documented with defaults and bounds. The description's 'keyset-paged via cursor; since stops at a date' largely restates what the schema says about `since`, adding little new syntax or edge-case detail, 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?

States a specific verb and resource ('Read the workspace audit log'), plus scope and ordering ('newest first'), and clarifies the payload ('who changed what, by name'). It is immediately distinguishable from siblings like get_proof_of_play and whoami.

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?

Explicitly routes the agent away from a plausible alternative: 'Use get_proof_of_play for what played on screens rather than who changed it.' That is a named alternative plus the condition that selects it, and the required permission is stated.

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

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

Annotations already establish readOnly/openWorld=false/destructive=false, but the description adds real operational behavior: results are scoped to locations the connection can see, only the newest 1000 files/apps are searched, scanCapped:true signals truncation, and ordering is newest-first. It stops short of explaining how limit/offset interact with the scan cap, so a 4 rather than a 5.

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?

Front-loaded with the core purpose and filters, then behavior, then sibling routing in a tight sequence. It is dense and mostly earns its sentences, though the per-asset return field list slightly duplicates the output schema.

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 an output schema exists, return values need not be restated, yet the description still covers scope, cap behavior, ordering, app handling and where to go for playlist/layout data. Nothing an agent needs to invoke it correctly 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%, so the baseline is 3, but the description adds meaning the schema lacks: kind:"app" returns app instances with their appKey, and narrowing via kind or folderId is the remedy when scanCapped is true. That cross-parameter guidance pushes it above baseline.

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 and resource (search the media library) and goes further by naming the filters (name, kind, folder, tag) and the cross-cutting use case (resolve names to asset ids before building playlists, casting or assigning). It is clearly distinguishable from siblings like list_items, get_playlist and search_screens.

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?

Explicitly routes the agent: use list_items for playlists/schedules/layouts and get_playlist for the contents of one playlist, and tells you to pass kind:"app" for apps only. The when-to-use and when-to-use-something-else conditions are stated directly.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), but the description adds genuine behavioral context: result visibility is scoped to 'locations you can see', pagination is capped at 200 per page with total/hasMore/nextOffset, and the scanCapped:true flag signals a 500-result search cap with the suggested remedy. None of this is derivable 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?

Front-loaded with purpose, then routing, then response/pagination behavior, then alternatives — a sensible order. It is dense and slightly over-packed (response-field details like location/region/playing sit close to filter guidance), but almost every clause carries actionable 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?

An output schema exists, so return values need no explanation; nonetheless the description covers pagination contract, visibility scoping, the scan cap, and routing to alternatives. Nothing needed to call this tool correctly 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%, so the baseline is 3. The description goes beyond it by stating that all filters are optional and combine with AND, and by tying nodeId/status to the scan-cap workaround ('narrow with nodeId or status'), which gives practical meaning to those two params.

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?

Opens with a specific verb and resource ('Find screens') plus the exact filterable facets (name, status, location, tag). It also states its role in the broader toolset ('turn a screen name into its id for any other tool'), which no sibling could claim, so an agent can distinguish it immediately.

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 explicit when-to-use ('Start here to turn a screen name into its id') and names two alternatives with their respective conditions: screen_health for single-screen diagnosis and list_open_alerts for open problems. This is the full when/when-not/alternative pattern.

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

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

Beyond the annotations (destructiveHint/readOnlyHint already flag a mutating call), the description explains the nature of the effect: 'Off makes the screen dark until it is turned on again' and 'the player keeps running either way'. It also discloses the required permission (`screen.edit`) and that unauthorized screens are silently skipped in bulk calls, which annotations cannot convey.

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?

Five tight sentences, front-loaded with the core action and scope, then consequences, then the alternative tool, then the permission requirement. No filler or redundant restatement of the name.

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 annotations covering safety traits and an output schema covering return values, the description fills the remaining gaps an agent needs: effect duration, player-side impact, CEC limitation, bulk skip behavior, and the `screen.edit` requirement.

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%, with power's enum and both screenId/screenIds already documented in the schema. The description confirms the bulk semantics of screenIds but adds no format, limits, or edge cases beyond what the schema provides, 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?

States a concrete verb (turn on/off) and resource (the TV attached to a screen) plus the transport mechanism (HDMI-CEC) and the single/bulk scope. It explicitly distinguishes itself from reboot_screen, so an agent can separate the two 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 alternative tool and the condition that selects it ('To restart the player instead use reboot_screen'), states the environmental precondition (TV must accept HDMI-CEC), and documents bulk-call behavior for out-of-reach screens. This is explicit when/when-not guidance.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing that the run is queued and returns a runId immediately, that content/soak/chaos/full change what the screen plays while running, and that these same suites additionally require `screen.cast` on top of `screen.edit`. This surfaces the destructive side effect and the extra permission requirement that annotations alone 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?

Front-loads the action, then the suite catalogue, then async behavior, then access restrictions — a logical order with no filler sentences. It is dense and somewhat wall-of-text, but each clause carries operational 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?

With an output schema present, return-value explanation is unnecessary, and the description nonetheless covers the async return contract, suite-specific access limits, permission prerequisites, and the competing single-frame tool. Nothing needed 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.

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

Schema coverage is 100%, so the baseline is 3, but the schema's own suite description defers to this text ('see the tool description'), and the description supplies real semantic content for each enum value (what 'smoke', 'chaos', 'content', 'requirements' actually do). screenId gains only marginal added meaning beyond the schema.

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 and resource ('Start an automated Device Lab test suite against a connected player') and explicitly distinguishes itself from the sibling capture_device_frame ('For one screenshot use capture_device_frame instead'). An agent can identify the tool without opening the 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 explicit conditions per suite variant ('chaos' and 'full' only on internal workspace or test-device screen; 'requirements' for internal workspaces), names the follow-up tool to poll (get_device_test_run), and routes single-frame needs to an alternative. When-to-use and when-not-to-use are both covered.

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

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

Goes well beyond the annotations: it states the return contract (synced:true, or synced:false with the feed's error), that errors are reported rather than thrown, that screens are notified on success, and the required permission (integration.edit at the data source's location). These are exactly the mutation-side effects an agent needs and that readOnlyHint/destructiveHint do not convey.

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?

Front-loaded with purpose, then return semantics, alternative, and permission — every clause earns its place. The first sentence is dense and runs long, which slightly hurts scanability, but nothing is redundant.

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?

Covers purpose, scoping to a single feed, the alternative tool, error behavior, side effects on screens, and required permissions. An output schema exists so return values need not be spelled out further; nothing needed to call it correctly 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 single dataSourceId is fully documented in the schema (ds_… from list_items kind data_sources). The description implies the id refers to one feed but adds no new format or constraint detail, 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?

States a specific verb+resource with scope: 'Pull fresh data through one connected feed ... now, instead of waiting for its scheduled sync.' It explicitly distinguishes itself from the sibling refresh_all_data_sources, so an agent can choose between them 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?

Gives an explicit when-to-use ('now, instead of waiting for its scheduled sync') and names the alternative with its selecting condition ('To sync every feed at once use refresh_all_data_sources'). Routing between the two sync tools is unambiguous.

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

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

Annotations already flag destructiveHint and openWorldHint, but the description goes further with non-obvious behavior: the call sets no end time (no automatic revert), it overrides existing casts and schedules, and it requires the `screen.edit` and `emergency-override.create` scopes. It also warns against guessing ids. That is exactly the additional context annotations cannot carry.

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?

Three sentences, each load-bearing: effect and scope first, then the irreversibility note, then sourcing/permissions. Front-loaded with the action and impact, no filler or restated 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 no explanation. For a destructive, single-parameter emergency tool the description covers impact, scope, irreversibility, prerequisites, alternatives, and required permissions — everything an agent needs to invoke it safely.

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 id prefix (etpl_…) is already documented, so baseline is 3. The description adds provenance and safety semantics beyond the schema: the id must come from list_emergency_templates and be operator-confirmed, never guessed. Small but genuine value over the schema.

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 (fire/trigger) and resource (emergency template) plus the concrete effect: every screen in the template's scope switches to it at once, above any cast or schedule. It explicitly distinguishes itself from the timed-message siblings quick_post and cast_content, so an agent can separate it from near neighbours without opening schemas.

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 an explicit when (real emergency, immediate takeover), an explicit when-not plus alternative ("For a normal timed message use quick_post or cast_content"), and the prerequisite workflow (fetch the id from list_emergency_templates and confirm scope with the operator). Nothing about tool selection is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description earns credit for scoping that destructiveness — the recycle-bin soft delete only fires via autoArchiveOnExpiry — plus stating the file itself is never modified. It also discloses the required `media.edit` permission, which annotations do not cover. It stops short of describing the response form, though an output schema exists.

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?

Three sentences, front-loaded with the mutation scope, then the merge semantics, then the sibling exclusion and the permission requirement. No filler, no repetition of the title, and the most decision-relevant clause comes first.

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 an 8-parameter mutation tool with full schema coverage, an output schema, and rich annotations, the description supplies everything else an agent needs: partial-update semantics, the destructive edge case, the alternative tool, and the auth requirement. Nothing material is left to inference.

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%, including the enum and null-clearing semantics for fit, altText, folderId and expiresAt, so the schema already carries the parameter burden. The description's field list is largely a restatement of those parameters rather than new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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 ('Update a media asset's metadata') and enumerates the dimensions it can change (name, tags, folder, alt text, fit, expiry), which maps cleanly onto the sibling set. It also explicitly distinguishes itself from configure_web_link, which an agent could plausibly confuse with 'change how media plays'. An agent can select this tool without opening the 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 alternative explicitly with the selecting condition: 'For a web link's crop, scroll or refresh use configure_web_link.' It also gives the operative usage rule that this is a partial/merge update ('Only the fields you pass change') so the agent knows not to send a full object. Both the routing decision and the invocation decision are covered.

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

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

With destructiveHint=true and idempotentHint=false already declared, the description goes well beyond them: it discloses the fixed step order, that a failure leaves earlier steps applied (non-atomic), that an edit can demote an approved playlist back to draft, that the response carries approvalState, and that `playlist.edit` is required at the playlist's node. That is exactly the kind of risk and auth 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?

Front-loaded with the purpose, then ordering semantics, then side effects, then sibling routing; every sentence carries information. It is a dense single paragraph that would read better as a short list, but there is no filler to cut.

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 an 11-parameter destructive mutation with a nested item-editing array, the description covers composition, ordering, partial-failure behavior, approval side effects, and required permission. Since an output schema exists, it only needs to nod at the return value, and it does so via approvalState.

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 per-field meaning is already documented, which sets a baseline of 3. The description earns an extra point by explaining how the parameters interact — the execution ordering of details/removals/item edits/appends/reorder and the ability to combine subsets — which is not derivable from the schema alone.

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 and resource ('Edit an EXISTING playlist') and then enumerates the concrete editable surfaces: rename/describe, play window, shuffle, append, remove, patch item duration/fit, reorder. This is unambiguous against siblings like bulk_create or assign_content.

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?

Explicitly routes the agent: 'Get item ids with get_playlist; to create new playlists use bulk_create.' It also tells the agent it may compose any subset of steps in one call, so the agent knows this is the single mutation entry point rather than model-level updating.

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

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

Annotations only declare the generic write/open-world/no-destroy profile; the description adds the operational specifics an agent actually needs: the 500 MB ceiling, that the asset lands at the workspace root and location-scoped keys are refused, and the required media.create permission. That is exactly the beyond-annotation context this dimension rewards.

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?

Five compact sentences, each with a distinct job: what it does, what it returns, when to use it, its limit plus the alternative, and its constraints. The purpose and scope are front-loaded with zero filler.

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, the description need not explain return values in depth, and it still names them briefly. Size limit, permission requirement, placement rule, and alternative tools cover everything an agent needs to call this correctly and to avoid mis-calling siblings.

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 schema already documents url, name, tags and folderId, including the root-filing default. The description reinforces the root-placement behavior but adds no syntax, format, or default detail the schema lacks. 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 and resource ('Copy a file from a public URL into the media library'), and explicitly contrasts itself with create_web_link ('show a live web page rather than copy a file') and mint_upload_url. An agent can distinguish it from every near sibling without opening a 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 a concrete use case ('migration: pull from a Drive share, S3, an old CMS export'), an explicit size boundary with the alternative for exceeding it (500 MB cap, use mint_upload_url for larger), and a routing rule away from create_web_link. When-to-use, when-not, and alternatives are all present.

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

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

Annotations already establish the safe-read profile (readOnlyHint, destructiveHint=false, openWorldHint=false), yet the description adds real behavior: what the actor field can contain, the branch confinement of a pinned key, and the caveat that the returned permission set is only a planning hint because node-precise checks still run on every write.

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, each carrying distinct information (identity, use context, key confinement, permission-set caveat), and the purpose plus use case are front-loaded. No filler or restated schema content.

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 no parameters, a present output schema, and full annotations, the agent needs only to know what the tool returns and why it matters. The description supplies exactly that, including the failure-mode diagnosis, so nothing material 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?

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to clarify. Nothing is missing, and the description usefully characterizes what comes back even though parameters are absent.

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+resource: it returns the acting identity (API key or signed-in user), the workspace id/name, and the permission set. No sibling tool does anything comparable, and the first sentence ('Who this connection is and what it may do') is an unambiguous purpose statement.

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 two concrete when-to-use conditions: 'at the start of work in an unfamiliar workspace' and as the diagnostic for 'an unexplained 403 or an empty list.' That is explicit routing guidance with no ambiguity about when this tool is the right call.

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