Brix Digital Signage

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds substantial context beyond annotations: the ~5 second wait, the fresh:false fallback for slow/offline screens, the 2 MB threshold that returns latestFrameUrl only, the screen.edit permission requirement, and the fact that it sends a device command. This reconciles the non-read-only annotation with the statement that screen content does not change.

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 organized into clear 'When to use', 'When NOT to use', 'What to know', and 'Parameters' sections. Every sentence adds distinct operational value with no repetition or 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 the description need not explain return values in detail, but it still covers the important edge cases (timeout, fresh flag, size limit, permission, id sourcing). For a screenshot tool with annotations and an output schema, this is complete enough 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% and the schema only says 'Screen id.', but the description adds the expected scr_… format, the source (list_items kind screens), guidance to call once per screen for multiple screens, and the error behavior for an id outside the connection's reach. This significantly exceeds the baseline 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?

The description states a specific verb and resource ('Take a new screenshot of one screen and return it as an image') and distinguishes itself from siblings by naming set_screen_content and control_screens as setup tools and get_screen_status as the diagnostic alternative. An agent can tell exactly what this tool does and when it is the right choice.

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 explicit 'When to use' and 'When NOT to use' sections, names the alternative for learning why (get_screen_status), and warns against polling in a loop. This is as clear as usage guidance gets.

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=true and non-idempotent, and the description adds non-obvious behavior beyond them: devices act within seconds but offline ones queue until they return, reboot blanks the display for ~a minute, clear_cache delays media but re-downloads files, tv_on/tv_off only work on HDMI-CEC TVs while the player keeps running, and screen.edit permission is required. It also points to capture_screenshot for verification.

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 layered structure (purpose, when/when-not, what to know, parameters, example) is front-loaded and skimmable, and nearly every line carries operational value. It is on the long side for a three-parameter tool, with some redundancy between the 'what to know' and 'parameters' sections, but nothing is wasted boilerplate.

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 document return values, and it instead covers the things that matter for a destructive, non-idempotent action tool: permission requirement, timing expectations, per-action side effects, and how to confirm the outcome. Nothing an agent needs in order 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?

Although schema coverage is 100% and the schema descriptions are bare ('Device action.', 'Screen id.'), the description supplies the real semantics: per-enum consequences and ordering advice (try refresh first), and the crucial combination rule that screenId and screenIds merge into one set, each screen is acted on once, and unreachable screens are silently skipped. It even gives a worked example.

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 ('Send a device action to one or many screens') and immediately differentiates itself from siblings by naming set_screen_content for content changes and refresh_data for feed/web updates. An agent can route to this tool 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 provides an explicit 'When to use' block with concrete symptoms (change not appeared, frozen screen, stale file, TV power) and an explicit 'When NOT to use' block that names the correct alternatives for content and data cases. This is the strongest form of routing 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?

Annotations only declare write/idempotency/openWorld flags; the description adds much more: which kinds are all-or-nothing (one bad row rejects the call and names it) versus created one-by-one with per-row ok/error, that a location whose externalId exists is skipped so re-runs are safe, that content at a location under review starts as a draft, that sign-in values are refused before anything is created, and a specific 403 failure mode for the repeat feature that should not be retried.

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 when-to-use / when-not before any mechanics, and the bullets are dense rather than padded. Some material duplicates the repeat schema block (secondsPerRow range, 403 feature_disabled) and the row-tag column-slug rules are long, but they encode real behavior the schema only gestures at.

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 18-kind write tool with 17 optional array parameters this covers what an agent needs: mutual exclusion of arrays, id prerequisites, partial-failure semantics, permission requirements, and the size limits (200 rows / 3 MB of slides). Return values are covered by an output schema, and the description still points to get_items repeatStatus fields for post-creation verification.

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 a constraint the schema cannot express: pass exactly one array whose name is the kind, and two arrays is an error. It also adds the cross-cutting rule that ids inside items must already exist and come from list_items, plus a worked playlist example. It does not re-explain most per-kind fields, which the schema already covers.

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 ("Create new items of one kind") and immediately scopes it against the sibling that handles the opposite case (update_items) and the ones that handle display (set_screen_content, start_takeover). An agent can route correctly 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?

Explicit when-to-use block enumerates the concrete cases (uploading bytes via media_files, public links via media_from_urls, pairing a device, inviting a person) and a when-NOT-to-use block names the alternatives to use instead. 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 already mark this as destructive and not read-only, but the description adds critical behavior: recycle-bin recovery, permanent deletion with a two-step confirmation flow, refused deletion cases, and permission requirements. It also describes side effects for deleted playlists, schedules, screens, and locations.

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 purpose, then organized into when to use, when not to use, behavior, and parameter notes. Every section adds actionable information without repetition or 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?

Given that this is a destructive mutation tool with complex permanent-delete confirmation behavior, the description covers prerequisites, alternatives, side effects, refusals, permissions, and parameter interaction. An output schema exists, and the description appropriately includes key response elements such as wouldErase, confirmCode, ok, and error without duplicating full return documentation.

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 still adds meaningful semantics beyond the schema: all ids must be of the specified kind, permanent deletion requires a first call and a confirmCode, and the confirmCode is time-limited and tied to the same kind and ids. The example further clarifies invocation.

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: deleting items into the 30-day recycle bin. It also clarifies scope and distinguishes the operation from adjacent actions by naming alternatives in the When NOT section.

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 says when to use the tool, including confirming the target first, and when not to use it. It names concrete alternatives such as update_items removeScreenIds and end_takeover for cases that should not use delete_items.

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 past the destructive/idempotent/openWorld annotations: it discloses immediate restoration of normal content, the idempotent success case (alreadyEnded:true), the failure mode for an unknown id (fails and lists what is running), and the required scopes (screen.cast / emergency-override.create). These are exactly the operational details an agent needs before firing a destructive call.

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 opening sentence states action and blast radius, then labeled sections (When to use / When NOT to use / What to know / Parameters) make scanning trivial. Dense but every clause carries actionable 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?

For a single required-parameter, destructive tool with an output schema, this covers discovery (list_items), permissions, idempotency behavior, and failure semantics; return-value detail is delegated to the output schema as expected. 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?

The schema only says 'Takeover id.', but the description adds that castId accepts a castId from start_takeover, an emergency id (emg_…), a content id, or the takeover's exact headline — and that the last two forms end every matching takeover. That is meaningful semantics the schema does not carry.

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 (End) plus resource (takeover or emergency) and scope (every screen it covers, in one call), which immediately separates it from start_takeover and set_screen_content. The sibling tools listed do not overlap with this scope, so an agent can route to it 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 enumerates when to use (tearing down what start_takeover started, early), when NOT to use (changing default content -> set_screen_content; per-screen looping), and points at list_items kind casts/emergencies for discovery. Alternatives and exclusions are named, not implied.

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, idempotentHint and destructiveHint=false, and the description still adds substantial non-structured context: it reads stored history only, scope is limited to screens the connection can see, and each report variant requires a distinct permission (screen.view, playback-log.view, audit-log.view). It also discloses that parameters belonging to another report are silently ignored, which is a non-obvious behavioral trait that would otherwise cause silent misconfiguration.

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?

Aggressively front-loaded and organized under 'When to use', 'When NOT to use', 'What to know' and 'Parameters'. The prose is compressed into fragments, but each one carries a distinct fact (permission, default, applicability, refusal rule) with no redundancy.

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?

This is a 10-parameter tool with three modes, and the description covers mode selection, per-mode parameter applicability, defaults, format requirements, permission prerequisites and scope limits, while the output schema carries the return shape. Nothing an agent needs in order 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 baseline would be 3, but the description goes well beyond the schema by mapping each parameter to the report types that honor it (from/to only for uptime and proof_of_play, since/limit/cursor only for audit_log), specifying ISO 8601 with rejection of non-ISO values, stating defaults (whole stored window, 30 days for uptime, limit 50), and giving a worked example. The only thing it omits is clarity that cursor is the previous page's nextCursor, which is already 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?

Opens with a specific verb and resource ('Read a report across screens for a time window') and immediately enumerates the three report types (uptime, proof_of_play, audit_log), so an agent knows exactly what the tool returns. It also explicitly separates itself from get_screen_status and list_items, which are the closest 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?

Provides explicit 'When to use' and 'When NOT to use' blocks, naming concrete alternatives for each exclusion ('One screen's detail: use get_screen_status. What is wrong now: use list_items kind alerts'). This is the strongest form of routing guidance: the agent never has to infer which sibling to pick.

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, idempotent, non-destructive and closed-world, yet the description still adds real operational context: per-id partial failure ('Each id returns its item or not found; the rest still return'), redaction of stored feed/link credentials, out-of-scope items surfacing as not found, rowCount being null when the data source is unreadable, and the polling instruction for device_test_runs. The only shortfall is that it does not mention the 50-id cap enforced by the schema or response size/pagination characteristics.

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 statement, then cleanly sectioned into when/when-not/what-to-know/parameters, so an agent can skim to what it needs. It runs long and some of the repeatStatus field inventory (loopSeconds, columns, missingColumns, firstRowBindings) is arguably return-value detail that the output schema already carries.

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 2-parameter tool spanning 18 kind values with heterogeneous return shapes, the description covers the selection decision, id construction, partial failure semantics, credential redaction and the one special kind. With an output schema present it need not enumerate return fields, and the extra detail on repeating creatives is helpful rather than redundant.

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 already 100%, so this had a low bar, but the description still adds genuine meaning: ids are prefix-typed (pl_, scr_, sch_) and sourced from list_items, they are required for every kind except account, and each id independently succeeds or fails. The worked example plus the account special case ('takes no ids and returns this connection's actor, workspace and permissions') tells an agent how to construct calls for an enum value the schema cannot explain.

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 ('Read items of one kind in full') and immediately separates itself from the two siblings an agent would most plausibly confuse it with — list_items for name search and get_screen_status for screen health. The reader knows it is a full-detail fetch keyed by kind and ids.

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 NOT to use' sections name concrete preconditions (before update_items to capture part ids) and redirect to the correct alternatives (list_items, get_screen_status) with the reason for each. 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 carry readOnlyHint/idempotentHint/destructiveHint/openWorldHint, but the description adds behavior the annotations cannot: it reads previously-reported data and 'never contacts it' so it works for offline screens, and it requires screen.view. These are non-obvious operational facts.

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 purpose followed by labeled When/NOT/What to know/Parameters sections, ending with a concrete call example. The density is all signal — every bullet conveys a constraint or routing rule.

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 4-param read tool with an output schema present, the description covers purpose, routing, data-source behavior, permissions, per-view parameter semantics, and an example. No agent-relevant gap remains; return shape is delegated 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%, yet the description goes far beyond it: each enum value is defined (why = source on screen; diagnose = cause plus checklist, with the guided:true caveat; outages; tv with a Signage-Sticks-only restriction), and per-view defaults, maxima, and which params are ignored are all given.

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 opening line 'Explain the state of one screen' states a specific verb and resource, and the 'When NOT to use' block explicitly routes to siblings (get_items kind screens, get_fleet_report, capture_screenshot, control_screens). An agent can distinguish this from every nearby tool 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?

Usage is spelled out in both directions: 'Why a screen shows what it shows, why it is blank or wrong, when it was down, or what its TV did' for when to use, plus four named alternatives each with the condition that selects them.

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, idempotent, non-destructive), and the description adds real value on top: short row shape, visibility limited to locations this connection can see, an unreadable kind raises an error rather than returning [], people/roles are read-only with privilege escalation blocked in the console, and newest-first ordering for media/alerts/recycle_bin. The 30-calls-per-minute rate limit and the advice to page with offset instead of re-listing are exactly the kind of operational 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 one-line purpose, then scannable labelled sections, so an agent can jump to the relevant block. It is long and some sentences are heavily nested with parentheticals (the connectors row setup line), but almost no text is redundant given 12 parameters and 21 kinds.

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?

Return format is covered by the output schema, so the description does not need to restate it, and everything an agent needs to call correctly is present. One gap: it instructs using "get_items kind account" while "account" is not in the kind enum, which would make that follow-up call fail as written.

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 would be 3, but the description goes well beyond it: it maps each filter to the kinds it applies to (status for screens/approvals, nodeId for screens and alerts with different depth semantics, tag for screens/media, binKind for recycle_bin), states filters combine with AND and are ignored on kinds they do not name, and gives page-size defaults (50 for media/approvals, 100 otherwise) plus offset/nextOffset paging. The worked example anchors the filter combination.

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 ("List items of one kind with their ids") and states the downstream reason ("so other tools can act on them"), which immediately distinguishes it from get_items and get_fleet_report. The kind enumeration and the note that rows are id+name+counts make the boundary even sharper.

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 NOT to use" sections name the alternative tools and the conditions that select them (get_items for one item's contents, get_fleet_report for history). It also gives positive triggers such as needing an id for a named screen, playlist or location.

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, idempotentHint=true, destructiveHint=false) by disclosing that settings never change, that failures surface in the result rather than as thrown errors, that permissions integration.edit / media.edit are required, and that allDataSources is throttled to 5 calls a minute. The Google-side propagation caveat (up to ~5 minutes; 'synced true' means the sync ran, not that the edit landed) is exactly the kind of trap an agent could not infer 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?

Front-loaded with the imperative sentence and cleanly sectioned into when/when-not/what-to-know/parameters, with no filler. The 'What to know' bullet is dense and multi-topic, packing permissions, failure mode, propagation delay, and verification advice into one block, which slightly hurts scannability even though almost every clause carries weight.

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 three-parameter, mutually exclusive, permission-gated tool this covers requirements, throttling, partial failure, and stale-read verification, and an output schema already documents return values. Nothing an agent needs to call it correctly or interpret the result 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?

Although schema coverage is 100%, the schema only offers one-word descriptions ('Web link id.', 'Every data source.'). The description adds the decisive rule that exactly one of the three must be passed, gives ID prefixes (ds_…, med_…), and explains how to discover IDs via list_items kinds, plus the sequential and partial-failure semantics of allDataSources.

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 opening line states a specific verb and resource: pull fresh content now rather than at the next scheduled refresh, and the title clarifies it covers both data sync and web-link re-render. It is clearly separable from siblings that change settings (update_items) or manipulate screens (control_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?

Explicit 'When to use' and 'When NOT to use' sections name the exact alternatives: update_items for settings changes and control_screens for a screen that is frozen or not picking up a change. The excluded cases are routed to a specific sibling rather than 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 annotations (readOnly=false, destructive=false, idempotent=true), the description discloses that restored items become usable again by dependent objects, that screens self-re-pair when the device still holds pairing, per-id ok/not-found reporting, and the required delete permission. That is substantial behavioral context the agent could not infer from the hints 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-loaded one-line purpose followed by labeled sections (when to use, when not to use, what to know, parameters) and a concrete example. Every line carries distinct information with no restatement of the 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?

For a two-parameter mutation with an output schema present, nothing essential is missing: the permission prerequisite, the 30-day failure mode, the id cap, and the enum naming convention are all covered. Return values needn't be explained because an output schema exists.

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: kind must use the list_items plural kind name (a recycle_bin row of kind playlist is restored with kind playlists), ids come from list_items kind recycle_bin, and the two distinct per-id error cases are spelled out. It stops short of explaining every enum value, so a 4 rather than 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?

"Bring back deleted items of one kind from the 30-day recycle bin" states a specific verb (bring back/restore) plus the resource and its scope (one kind, 30-day bin). It is immediately distinguishable from delete_items, list_items, and get_items.

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" names undoing delete_items, and "When NOT to use" names the 30-day expiry case with the resulting not-found behavior. The agent has a clear routing rule plus an exclusion, and the sibling delete_items is named 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?

Goes well beyond the annotations by spelling out what each decision does to the content (approve airs it immediately, reject keeps it off screens, withdraw returns it to draft), that all three are final, and the exact authorization requirement per decision. It also documents the refusal behavior when the caller lacks a role in the chain.

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, then cleanly sectioned into when/when-not/what-to-know/parameters. Every line carries information, though the heading scaffolding is slightly heavier than a three-parameter tool strictly needs.

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 destructive, non-idempotent mutation with an output schema available, the description covers effects, finality, authorization, and parameter sourcing. An agent has everything needed to choose a decision correctly or know it will be refused.

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 descriptions are one-word ('Why.', 'Approve, reject or withdraw.'), so the description does the real work: it identifies approvalId as an ar_… id sourced from list_items kind approvals and explains that reason is required and shown verbatim for reject, optional for approve, and ignored for withdraw.

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 opening sentence gives a specific verb set (approve, reject, withdraw) and a precisely scoped resource (one pending approval request). It is unmistakably distinct from siblings like create_items, update_items, and delete_items.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'When to use' and 'When NOT to use' sections, with the alternative named (update_items, because an edit opens a new request) and the prerequisite stated (this connection's person must be an approver). 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?

Beyond the destructiveHint/idempotentHint/openWorldHint annotations, the description discloses the permission required (screen.cast), the propagation latency ('screens update within seconds'), and partial-failure semantics: unsupported or approval-gated screens are skipped and counted via notShared/needsApproval while the rest still change. That skip-and-count behavior is exactly the kind of outcome an agent cannot infer from destructiveHint=true 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?

Labeled sections (When to use / When NOT to use / What to know / Parameters) front-load the routing decision, and the worked example is compact. It is dense and slightly long, with the parameter block partly restating schema field names, but almost every line carries non-redundant 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?

For a destructive, idempotent bulk-mutation tool, the description covers selection semantics, clearing behavior, bulk partial-failure outcomes, auth requirements, and latency. Return values are covered by the existing output schema, so nothing an agent needs in order 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 would be 3, but the description adds real meaning: screenId/screenIds/nodeId combine into a single union set with at least one required, nodeId expands to every screen at and under it up to 1000, contentKind null clears playback and is only legal with exactly one screen and no nodeId, and contentId originates from list_items. A concrete example call reinforces the combination rules.

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 with its scope: 'Set what screens play by default until it is changed again.' The persistence clause immediately separates it from a temporary takeover, and the when-to-use line enumerates the target shapes (one screen, a list, a location subtree).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use and when-NOT-to-use sections name the two decisive alternatives: start_takeover for self-terminating takeovers and update_items for changing playlist contents. Each alternative comes with the condition that selects it, and the parallel hint ('every screen playing it follows') explains the consequence of picking wrong.

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 that content self-expires, that an emergency persists above everything until end_takeover, that the call requires the screen.cast permission, and that it returns castId for the paired end_takeover tool. These are non-obvious operational traits (permission, lifecycle, follow-up call) that the destructive/openWorld hints alone 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 imperative sentence followed by tight labeled sections (when to use, when not to use, what to know, parameters). Every line carries decision-relevant information; 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?

For an 8-parameter mutation with an output schema, the description covers selection guidance, permission prerequisites, precedence rules, defaults, and the paired cleanup tool. With the output schema handling return shape, 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 coverage is 100% so the baseline would be 3, but the description adds real meaning the schema lacks: the mutual-exclusion rule ('pass exactly one of contentId+contentKind or emergencyTemplateId'), the default for scopeKind and its per-value semantics, the emergency overriding scope, the one-hour default for expiresAt, and a worked example.

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 ('show something on screens over their normal content, now') with an explicit temporary-behavior qualifier. The 'When NOT to use' line names set_screen_content, so an agent can separate it from the sibling 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 cases (temporary override like a lunch menu, or a pre-armed emergency) and an explicit when-not-to-use case routed to set_screen_content. Emergency vs temporary content handling is also called out as a decision the agent must confirm with the person.

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?

The annotations already flag mutation, destruction, non-idempotence, and open-world behavior, but the description adds substantial operational context: per-id step ordering, partial failure semantics, review/draft behavior, permission requirements, immediate live changes, no undo, feature-disabled errors, and row-limit warnings. It also explains bulk-update behavior and the fact that each id receives identical changes, which is critical beyond 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?

The structure is front-loaded and useful: purpose, when/when-not, what to know, then parameters. It is long, but the length is largely justified by the tool's complexity; some repeat/row-tag details duplicate or expand schema-level information, keeping it just short of ideal concision.

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 destructive bulk-update tool, the description covers permissions, failure behavior, live propagation, undo risk, feature restrictions, repeat-row semantics, limits, and error handling. Output schema exists, so it does not need to describe return structure in detail, and its mention of get_items/repeatStatus is useful rather than redundant.

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 parameter schema already carries much of the field-level meaning. The description still adds valuable cross-parameter semantics: all ids must be the same kind, every id gets identical changes, missing fields are unchanged, whole-value replacement for zones/boxes/config/tags requires get_items first, sentinel secret handling in config, and a concrete example call.

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 and scope: "Change existing items of one kind, the same changes on every id." It explicitly distinguishes the tool from set_screen_content, create_items, and delete_items, so an agent can choose it without inspecting 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?

It has explicit "When to use" and "When NOT to use" sections, naming alternatives such as set_screen_content, create_items, and delete_items. The guidance is concrete enough to route an agent correctly across the most likely sibling tools.

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