Screenbird

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

Annotations already declare destructive=true and idempotent=true, so the safety profile is covered; the description still adds value by spelling out what is displaced ("in place of what it shows"), the precondition that screens must be online with a paired player, and that results carry online/paired fields. That last point matters because there is no output schema.

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 effect in the first clause and adds two supporting sentences that each carry information (re-run semantics, readiness precondition, result fields). Slightly dense but no wasted sentences.

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 what the tool does, the fact that it replaces current content, the readiness requirement, and what the response indicates, which is important since no output schema exists. Complete enough to call correctly; only the relationship to release_scene 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?

There is a single required scene_id, and the schema already encodes its UUID pattern (^[0-9a-fA-F-]{36}$) even though description coverage is nominally 0%. The description adds no meaning about the identifier, so it neither compensates nor needs to do much for one well-constrained field.

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 with the actual effect: putting a scene live makes every screen and sub-screen in the scene switch at once. An agent can distinguish this from check_device or push_content, though it never names the obvious alternative release_scene, so sibling differentiation is only implicit.

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?

"Running it again puts changes to the scene live" usefully clarifies the repeat-call case, and the online/paired precondition gives context for when activation will actually take effect. However, it never says when to prefer this over release_scene or release_all, leaving the exclusion guidance 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 readOnly, idempotent, non-destructive, closed-world lookups, so the safety profile is covered. The description adds genuinely new behavioral information: the closed set of five possible status outcomes plus an accompanying explanation, which is important for an agent interpreting results since there is no output schema.

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 the action and followed by the outcome vocabulary; every clause earns its place, including the illustrative device names. Minor slack in the trailing 'with an explanation', which is slightly vague about what the explanation contains.

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 one-parameter, no-output-schema lookup, the description covers input semantics and return values, which is nearly everything an agent needs. The remaining gap is ambiguity handling — how the tool behaves with a misspelled or unsupported device name beyond returning 'unknown'.

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 0% and the single 'device' parameter is an untyped string with only maxLength, so the description must carry the meaning — and it does, clarifying that the value is the device as the user names it, with concrete examples. It still doesn't say how loose matching is or what to do with an unrecognized name (beyond the 'unknown' return).

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 ('Check whether a device ... works with Screenbird') and enumerates the exact outcome vocabulary (works, coming_soon, does_not_work, works_in_browser, unknown). This clearly separates it from siblings like get_install_steps or search_help, which are about setup and documentation rather than compatibility lookup.

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

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

Gives clear triggering context — a user-nameable device such as "Samsung TV", "Chromecast", "iPad" — which tells the agent when this tool applies. It stops short of naming an alternative or exclusion (e.g. when to prefer get_install_steps or search_help instead), so it is clear but not fully routing.

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 description discloses important behavior beyond the annotations: it selects a template, fills text and stock photos, explicitly does not generate images with AI, saves the design to team files, and consumes the account's AI budget with a rate limit of at most 20 designs per hour. These details materially inform safe and correct invocation.

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 and artifact definition, then adds relevant operational details in a compact sequence. Every sentence contributes useful context about generation, saving, usage, and budget constraints.

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 four fully documented parameters, rich annotations, and no output schema, the description covers purpose, generation behavior, persistence, and rate limits well. It does not describe what is returned after creation, such as a design identifier or confirmation, which leaves a minor gap for an agent that needs to act on the created design.

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 name, brief, language, and orientation thoroughly. The description reinforces that creation is driven by a 'description' and mentions template text and stock photos, but it does not add parameter-specific syntax or constraints 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?

The description uses a specific verb and resource: 'Create a design', then immediately defines the artifact as a full-screen slide for a screen, such as a menu, announcement, or event poster. This makes the tool's purpose unambiguous and distinguishes it from content-pushing or scene-activation 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 gives clear usage context by explaining that the design is generated from a brief, picks a fitting template, and is saved in the team's files for use on a screen or in a scene. It does not explicitly state when to use this instead of siblings like push_content or search_content, but the intended context 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 already declare the safe, read-only, idempotent profile, so the description's added value is its disclosure of the return content: a step sequence that culminates in a pairing code the user enters in the dashboard. That is meaningful context an agent could not get from the annotations, and with no output schema it is the only signal about response shape. It stops short of noting whether steps are device-specific or how the pairing code behaves.

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 front-loaded sentence with no filler. The result content (steps ending in a pairing code) is placed at the end where it reads as a natural payoff.

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 one-parameter read-only lookup with no output schema, the description covers what the tool produces and that a pairing code is involved, which is the key downstream detail. Missing only enum-value guidance and any note on device support limits.

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 0%, so the description must compensate. Saying 'on a device type' identifies the parameter's role, but it does not enumerate or explain the eight allowed enum values (signage_stick, fire_tv, browser, etc.) or clarify what happens with unsupported devices. Partial compensation only.

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: produces installation steps for the Screenbird player, scoped to a device type. An agent can immediately tell what it returns. It does not explicitly separate itself from siblings, though none of the listed siblings overlap with install guidance.

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

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

Usage is implied by the phrasing 'Steps to install the Screenbird player' – call it when a user needs to set up a device. There is no explicit when-to-use, when-not-to-use, or named alternative, so guidance remains inferential.

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 non-destructive behavior, so the description earns credit for adding what they don't: pagination via next_cursor and the target truncation rule (max 20 targets per scene, targets_total is authoritative). It stops short of describing ordering guarantees beyond 'in their order' or any filtering behavior.

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 resource and scope, then return shape, then pagination — no filler. The parenthetical about targets is dense but earns its place because it prevents a misinterpretation of the truncated list.

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 output schema, the description must hint at return shape, and it does: scene order, state values, screen/sub-screen targets, and pagination. It leaves the exact per-scene object fields and default ordering semantics unstated, which is a minor gap for an agent that only needs to list and page.

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 limit (1-100, default 25) and cursor as the next_cursor from the previous page. The description's 'pass next_cursor as cursor for the next page' restates the schema rather than adding syntax or edge-case guidance, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('List the team's scenes') and adds scope ('in their order') plus what is returned. It is clear on its own, but it never contrasts itself with the sibling list_screens, so an agent must infer the split from the names alone.

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

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

Usage is only implied by the description of the returned data; there is no explicit statement of when to call this versus list_screens, activate_scene, or release_scene. The pagination instruction tells the agent how to continue, not when to choose this tool.

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, closed-world), so the description's job is added context; it delivers by disclosing the exact content states a screen can be in, the presence of an optional end time, the extra account-level fields (time zone, local time), and the cursor-based paging contract. It does not cover ordering or what 'online status' values look like, which keeps 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?

Front-loaded with what is returned, then filtering, then pagination — a sensible order for an agent. It is a single dense block with a couple of expendable phrases ('if there is one'), but nothing is wasteful enough to obscure the 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?

There is no output schema, so the description carries the return-value burden and does so well: it names the per-screen fields, the account-level fields, and the pagination token. Minor gaps remain around result ordering and the possible values of online status.

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 all four parameters are already documented. The description restates query and screen_id semantics and the next_cursor-to-cursor flow, adding little beyond the schema, and never mentions limit or its default of 25. 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 ('list the connected team's screens') and immediately enumerates the returned fields: online status, current content type (normal, pushed, scene, mirroring), end time, time zone and local time. This clearly separates it from siblings like list_scenes or search_content, which retrieve different objects.

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 explains how to narrow results (query or screen_id) and how to page, which implies the retrieval use case, but it never states when to prefer this over list_scenes or search_content, nor any exclusion or prerequisite. Usage is implied rather than prescribed.

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?

Adds real context beyond the annotations (destructiveHint/idempotent/readOnly already declare the safety profile): it discloses that existing screen content is displaced, that display persists until a time or manual revert, and that the screen must be online with a paired player. The return value ('what the screen shows afterwards', including online/paired) is described. It does not say what happens to the displaced content or whether the disruption is user-visible to viewers.

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 core action and persistence rule front-loaded and prerequisites/return info after. Dense but every sentence carries distinct 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 a 4-parameter mutation tool with no output schema, the description covers preconditions, persistence, split-screen targeting, and the shape of the response. Remaining gaps are minor: no mention of required permissions/account scope or how a failed push manifests.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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

Schema description coverage is only 25% (only 'until' is documented), so the description must compensate. It does explain subscreen_id's requirement for split screens and the indefinite behavior when 'until' is omitted, but screen_id and content_id get no added meaning beyond their names — e.g. whether content_id must pre-exist or which content types are valid is unstated.

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 ('show content on one screen, or on one sub-screen of a split screen') with precise scope: it replaces current output and persists until a time or until reverted. This implicitly distinguishes it from the release_* siblings, which restore normal state rather than 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?

Gives clear conditional guidance: a split-screen target requires subscreen_id, and omitting 'until' means indefinite display. It does not name release_screen or release_all as the way to undo the push, nor state when a different tool (e.g. activate_scene) would be preferred, so it falls short of full when/when-not routing.

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, idempotent=true and readOnly=false, so the safety profile is covered. The description adds real value beyond that by disclosing the side effect that screen mirroring keeps running - i.e. what is NOT torn down - and by scoping the blast radius to the team's screens.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The destructive action leads, and the non-obvious side effect about mirroring follows immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-param, annotation-rich, no-output-schema tool the description covers the essentials: the breadth of the destruction and one key exception. It could optionally note whether this is a team-wide reset affecting every screen or whether it is scoped to a session, but that is a minor 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?

The tool takes zero parameters with 100% schema coverage, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter claims are made because none exist.

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 the resources affected ('all scenes and all pushed content on the team's screens'), which is concrete enough to act on. The 'all' scope implicitly separates it from release_scene and release_screen, but the contrast is never made explicit.

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

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

Usage is only implied: 'all' suggests a team-wide reset as opposed to the per-scene/per-screen siblings, but the description never states when to prefer this over calling the singular tools.

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, idempotentHint=true and readOnlyHint=false, so the bar is lower. The description usefully explains what 'destructive' means here — screens return to their own content — but doesn't say what happens to the ended scene's layout/content, whether it can be reactivated, or what state screens were in before.

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 compact sentence with the effect front-loaded and no filler. Brevity tips into under-specification rather than excess.

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?

No output schema exists, so return behavior needn't be described, and annotations cover the safety profile. Still missing: what happens to the scene resource itself, whether activation is a prerequisite, and any pointer to the scene_id source — gaps that matter for a destructive mutation.

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 0% and the description never mentions scene_id, its UUID format, or where to obtain one (presumably from list_scenes). With a single undocumented parameter, the description fails to compensate for the schema gap.

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 action (end a scene) and its visible effect (its screens revert to their own content), which implicitly contrasts with activate_scene and release_all. It doesn't name those siblings, so differentiation is inferred rather than explicit.

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

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

No guidance on when to use this versus release_all or release_screen, and no preconditions (e.g., must the scene be active first?). The agent must guess from the name alone.

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=true already declared, the description adds genuine context by defining what 'destructive' means here: pushed content or a scene is ended and the screen reverts to its own content. It doesn't cover auth requirements or what happens if nothing is currently pushed, but the core effect is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no filler; the effect ('goes back to its own content') is stated immediately after the action. Nothing is redundant, though slightly more structure would help given two parameters.

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 tool with annotations covering the safety profile (destructive, idempotent) and no output schema, the description covers the action, target scope, and resulting state. Nothing essential 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 description coverage is 0%, so the description must carry parameter meaning. It partially compensates by referencing 'one screen or sub-screen', which hints at screen_id vs. subscreen_id, but it never explains that screen_id is required and subscreen_id is optional, nor what a sub-screen target implies for the operation.

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 pushed content or a scene') and resource scope ('one screen or sub-screen'), plus the observable outcome ('goes back to its own content'). It differentiates from release_all by scoping to a single screen, though it never names the sibling tools explicitly.

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

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

The single-screen scope implies when to use this instead of release_all, but that's left to inference. There's no explicit statement of when not to use it, and no mention of release_scene or activate_scene as alternatives.

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, idempotent and closed-world safety, so the description's job is lighter. It nonetheless adds real value by disclosing result ordering ('Newest first') and the returned fields (id, name, type), which matters because no 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 short sentences, each carrying distinct information: scope, ordering, and return shape. Lead sentence states the resource, and nothing is redundant with 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 no output schema, the description correctly supplies the return fields, and it states ordering. Minor gaps remain: no mention of default/max limit behavior or pagination, and no note on what happens when query is empty beyond the schema's own hint.

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 67%: limit and query are documented, while type is only self-describing via its enum. The description's enumeration of content types loosely mirrors the enum but adds no new constraint or format detail, so it neither compensates for nor worsens the coverage gap.

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?

Names a specific verb (Search) and resource (team content shown on a screen), then enumerates the five content types so the agent knows exactly what is searchable. It does not explicitly contrast with siblings like list_scenes, but the resource scope is distinctive enough to avoid confusion.

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

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

The description implies a search/browse use case via 'Newest first' but never states when to use this versus list_scenes or search_help, nor any prerequisites. Only the schema's 'Leave empty to list recent content' hints at the browse mode, so guidance is implied rather than 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 declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior that annotations cannot: a hard cap of 3 articles, the fields returned, and that 'full' expands to complete article text — valuable since there is no output schema.

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 the verb and resource, then the return contract. Every clause carries information — result cap, field list, and the full-text toggle — 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 no output schema, the description accepts responsibility for the return shape and does so (up to 3 articles, title/summary/link). The only omission for a search tool is ranking or result-count behavior when zero matches are found, which is a minor 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%, so the baseline of 3 applies. The description restates the 'full' flag in behavioral terms (complete text of each article) but adds no syntax or semantics for query or language beyond what the schema already documents.

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 Screenbird help center' — and scopes the content with concrete categories (features, setup, troubleshooting). It is clear what it retrieves, though it never names the sibling search_content, so an agent must infer that this tool is the help-doc counterpart rather than the content-search one.

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

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

The parenthetical 'how features work, setup, troubleshooting' effectively enumerates the situations this tool covers, which is stronger than implied usage. There are no explicit exclusions or named alternatives, so it stops short of full 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.