mcp-screen

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

With no annotations, the description carries the full behavioral burden and does well on the most non-obvious trait: it BLOCKS until a click or timeout, and it discloses the return shape including the {answered:false, reason} unanswerable case. It omits failure/error semantics and any timeout-visibility caveats, but the blocking disclosure is the crucial one and it is front-loaded.

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 with zero waste; the blocking behavior and return format are front-loaded where an agent needs them before committing to a call. No filler or 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?

For a blocking interactive tool with no annotations and no output schema, the description supplies the essentials: what happens on the canvas, that the call blocks, and the exact return shape. It could say more about timeout expiry consequences, but nothing critical 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 50% (question and the choices container lack descriptions). The description adds conceptual meaning (cards are clickable, choices yield {id,label}) but does not document the choices min/max constraints, the id/label contract, or the timeout default beyond what the schema already states. Baseline 3 is appropriate at partial coverage.

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 ('Ask the human a visual question') and describes the mechanism (clickable choice cards on the canvas). It is clearly distinguishable from canvas-manipulation siblings like place_widget or read_canvas, since it is a blocking human-in-the-loop prompt rather than a widget operation.

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 gives when-to-use context: 'decisions that are easier to make by looking: layouts, copy options, which bug to fix first.' This is clear situational guidance, but it does not name alternatives or state when NOT to use it (e.g., when a plain text question would suffice).

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 no annotations, the description carries the full behavioral burden and does well: it discloses destruction scope (all widgets), what is preserved (standup cards), and reversibility via two distinct undo routes. It omits permission/auth requirements and any effect on other collaborators, leaving modest gaps for a destructive operation.

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

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

Two sentences, zero waste, with the destructive scope and its exception front-loaded before the recovery guidance.

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, no-output-schema tool this is nearly complete: it covers scope, exception, and reversibility. It does not mention what the call returns (e.g., count of removed widgets) or failure modes, which are the only remaining gaps.

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 value beyond the schema: it clarifies that undo should be invoked 'right after' the clear, a temporal coupling the schema's 'last clear' wording only implies.

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 ('Remove every widget from the canvas') plus an explicit scope exception ('standup cards stay'). This is distinguishable from the sibling remove_widget, which acts on a single widget, 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?

The bulk-clear use case is clear, and the description routes the agent to the recovery path (human undo or re-invoking with undo:true). It does not explicitly say when to prefer the sibling remove_widget for a single widget, so it stops short of full 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?

With no annotations, the description carries the behavioral burden and does so well: it discloses that live sources re-run server-side with no LLM, that 'NOTHING runs until the human clicks Approve on the canvas,' that approved sources go on a persistent allow-list, that livemap nodes light up on matching file edits, and that source output must match the widget data shape. These are non-obvious, high-consequence behaviors the schema does not 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?

Purpose and return value are front-loaded in one sentence, then a tight bulleted payload catalogue follows. It is long, but nearly every line is load-bearing for an 8-kind polymorphic tool; only the parentheticals (e.g. 'sortable', 'monospace log/output') shade into extra detail.

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, nested, no-annotation tool this covers the essentials: kinds, payload shapes, live-source gating, refresh interval, and the returned id. It omits secondary behavior an agent might need — default layout/size handling for h/w/w, whether an existing id collides or updates, and any widget-count limits — but nothing that blocks a correct call.

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's `data` field is a bare 'Payload matching the kind (see description)' pointer, so the description is the only place the per-kind payload contracts are defined (table columns/rows, chart type/labels/values/linkTo, metric, kv, status-list statuses, livemap nodes/globs/edges). At 75% coverage with 8 params and deep nesting, this compensates fully 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 verb and resource ('Show something to the human on their mcp-screen canvas') and the return value ('Returns the widget id'), which clearly frames this as the creation/display tool. The eight-item widget-kind list reinforces that this is the create path. It never explicitly names or contrasts with update_widget or read_widget, so sibling differentiation is left 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?

Usage is implied rather than stated: the widget-kind catalogue tells the agent what it can render, and the first sentence implies 'use this when you want the human to see something.' There is no explicit statement of when to prefer place_widget over update_widget, post_report, or ask_user, and no stated exclusions.

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 no annotations, the description carries the full behavioral burden. It discloses only that cards are 'grouped by worktree and agent on the Standup board'; it says nothing about permissions, whether posts are append-only or overwritable, side effects, or return behavior for a mutation tool.

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 tight sentences with the trigger and action front-loaded and no filler. Efficient, though it spends its second sentence on grouping metadata rather than on parameter guidance.

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 7-parameter mutation tool with nested objects (tests, filesChanged), no annotations, and no output schema, the description leaves significant gaps: the 'branch' param is unaddressed, nested required fields are unexplained, and posting behavior/auth requirements are undisclosed.

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 low at 29%, so the description must compensate. It does map several params to intended content — 'what you changed' (filesChanged), 'test results' (tests), 'a short summary' (summary), 'risks' (risks), and grouping by worktree/agent — but omits 'branch' and gives no format details for the nested tests/filesChanged structures.

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 ('Post a standup card') plus the trigger ('when you finish a task'). It is clear what the tool does, but it never distinguishes itself from the widget/canvas siblings (place_widget, update_widget, read_canvas, etc.), leaving the agent to infer that this is a separate standup-board concept.

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 when-to-use trigger: 'when you finish a task.' However, it names no alternatives and states no when-not-to-use condition, so routing versus the sibling widget tools 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?

With no annotations, the description carries the full burden. 'List' and 'live status' imply a non-mutating read and disclose the shape of the returned data, which is genuinely useful. However, it says nothing about ordering, pagination, or whether 'live status' reflects real-time state or a cached snapshot.

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 that front-loads the verb and scope and wastes no words while still enumerating the returned fields.

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

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

For a zero-parameter read tool with no annotations and no output schema, the description covers the essential behavior and even lists the returned fields. It stops short of describing ordering or scale limits, which would matter for a canvas with many widgets.

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 there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies the call is unfiltered, returning everything on the canvas.

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 (List) and resource (every widget on the canvas) and enumerates the returned fields (id, kind, title, live status, selection). It implicitly distinguishes itself from the sibling read_widget by scoping to 'every widget', though it never names that alternative.

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: 'every widget' suggests a bulk/inventory read as opposed to the single-item read_widget, but the description never states when to prefer this over read_widget or any other sibling. No exclusions or preconditions are given.

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?

No annotations exist, so the description carries the full burden, and it does disclose part of the return surface: `selection` and the livemap-specific `unmappedFiles`. However, it says nothing about error behavior (unknown id), side effects, or freshness, and no output schema exists to fill that gap.

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 tight sentences, front-loaded with the core action before the return-value details. The livemap aside is niche but short and actionable, though the backtick-heavy phrasing is slightly dense.

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 tool with no output schema and no annotations, the description partially compensates by naming key return fields. It still leaves the id semantics and failure modes undocumented, so an agent can call it but not fully anticipate the result.

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 single required `id` parameter has 0% schema description coverage, and the description never explains what the id refers to or its format. Since the parameter count is low the baseline is generous, but the description adds essentially no 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+resource ('Read a widget back') that clearly contrasts with the write-oriented siblings place_widget, update_widget and remove_widget. It never names a sibling explicitly, so differentiation is inferred from read-vs-write semantics rather than stated.

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 return-content framing ('what the human clicked'), which tells the agent this is how you learn about user interaction, but there is no explicit when-to-use versus read_canvas or when-not-to-use guidance. An agent must infer the routing from the verb.

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 no annotations, the description carries the full burden. It does disclose a genuine behavioral trait beyond the schema: removal also stops the widget's live refresh. It does not state reversibility, whether the call errors on an unknown id, or whether it takes effect immediately, so a meaningful gap remains for a destructive operation.

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 zero filler; the action is stated first and the secondary behavioral note is parenthesized. Nothing could be trimmed without losing information.

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

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

For a one-parameter tool with no output schema and no annotations, the description covers the action and one side effect, which is close to sufficient. Missing details about error behavior and reversibility are minor given the low 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 description coverage is 0% – the lone parameter is documented only as type string with no description. The tool text adds nothing about what the id refers to or its format, so it fails to compensate for the low coverage as required. Only the parameter's self-evident name keeps this from scoring lower.

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+resource ("Remove a widget") makes the action unambiguous. It also adds a side-effect clause about stopping live refresh, which the sibling names (place_widget, update_widget) do not. However, it never explicitly contrasts itself with update_widget or clear_canvas, so sibling differentiation is left 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?

Usage is implied by the name and the parenthetical note about live refresh, so an agent can reasonably infer when to call it. But there is no explicit when-to-use guidance, no mention of prerequisites, and no routing to alternatives like update_widget (modify) or clear_canvas (remove all).

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?

No annotations are provided, so the description carries the full burden. It does disclose a genuinely important behavioral trait — that `data` is shallow-merged by default and fully replaced with merge:false — which is exactly the kind of semantics an agent needs. However it says nothing about permissions, error behavior for a missing id, or whether omitted geometry fields (h/w/title) are preserved.

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 with no filler, and the default behavior (shallow merge) is front-loaded ahead of the override. The {edges} example is compact and earns its place by making the merge semantics concrete.

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 annotations and no output schema, so the description is the only behavioral source. It covers the highest-risk ambiguity (merge vs replace) well, but leaves permission requirements and the outcome of updating a non-existent widget unexplained for a mutation 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 description coverage is 0% across 6 parameters, so the description must compensate. It does well on the two non-obvious params, explaining `data` merge semantics with a concrete {edges} example and clarifying `merge:false`; id/title/h/w are left to self-evident naming and get no explanation.

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 ('Update an existing widget'), which cleanly separates it from place_widget and remove_widget in the sibling list. It does not explicitly name place_widget as the create-side alternative, so sibling differentiation is implicit rather than stated.

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 frames the tool as updating an *existing* widget, which implies it should be used only after the widget exists, but it never says when to prefer place_widget or what to do if the id is unknown. Usage is implied by the verb and the merge discussion, not stated.

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