Showboard

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

With no annotations, the description carries the full burden and does disclose the payload: tables, columns, estimated row counts, and named data sources, including the "estimated" qualifier that warns against relying on counts as exact. It stops short of saying whether the listing is live/cached or how large a result can be, which matters for a zero-parameter exhaustive listing.

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, no filler, and the content of the listing is front-loaded before the usage instruction. Every clause earns its place by naming either a return field or a consumer tool.

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

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

No output schema exists, yet the description enumerates the return contents well enough for an agent to know what it will get and to route it to query_data or use_source. Minor gap: no hint about result size, freshness, or what an empty catalog means.

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 no parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies a single no-argument call returning the full catalog.

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 the exact resources enumerated: database tables/columns usable by query_data, plus the app's named data sources for use_source. It distinguishes itself from the two sibling tools that consume its output, so an agent can tell what it returns versus what query_data and use_source do.

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?

"Call it before writing SQL against tables you have not seen" is an explicit when-to-use rule with a clear precondition (unfamiliar tables). Naming query_data and use_source as the downstream consumers makes the alternative-selection implicit but unambiguous.

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

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

With no annotations, the description carries the burden and mostly delivers: it constrains SQL to a single read-only SELECT, states that every number is computed by the database, discloses the return behavior ('returns the rows of each part, the first and last of long ones'), and explains that save_as persists a reusable recipe. It does not address side effects like what happens to existing boards or any permission/rate constraints.

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 a bulleted item grammar and a component glossary, which is the right structure for a deeply nested schema. It is longer than ideal and the component glossary largely restates what the schema already documents (e.g. Note text/bullets/bold, tone), which is redundant 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 6-parameter tool with deep nesting and no output schema, the description covers the essentials: item shapes, chart auto-selection rules, SQL/params discipline, recipe reuse, return-value behavior, and an escape hatch via get_screen for custom components. Nothing an agent needs to construct a valid call 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 83%, so the baseline is 3; the description earns an extra point by explaining how params (:name placeholders) tie to SQL, how save_as turns params into recipe inputs, and how show/x/y/series/formats interact to pick a chart versus providing component+props. It adds genuine semantics beyond the field-level text, though it doesn't clarify id or preview_rows.

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 precise verb+resource+scope: 'Draw a board on the user's screen in one call.' It then enumerates the item grammar concretely (part / note / row / section), so an agent knows exactly what the tool produces versus a read-only sibling like query_data or describe_data. It also points at get_screen for app-specific extensions, which sharpens its boundary.

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 actionable routing guidance: use recipe when the same board must be re-rendered for other param values, use get_screen to discover app actions/components, and 'aggregate, rebase and round in SQL' rather than post-processing. What's missing is an explicit statement of when to call draw versus show_board/list_boards, so the create-vs-view boundary is left implicit.

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 discloses the substantive behavior: it is a snapshot read of live screen state and a required precursor to ui_act. It does not explicitly state that the call is side-effect free, nor how fresh the snapshot is or what happens if no browser is attached, keeping it below a 5.

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

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

Two sentences, front-loaded with the core identity before the usage rule. The first sentence is a dense four-item enumeration packed into one clause chain, but every item carries information an agent 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?

No output schema exists, and the description compensates by enumerating what the snapshot contains, which is exactly what is needed. Missing only the relationship to sibling board tools (show_board, list_boards) for an agent deciding where to look first.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The parenthetical about ui_act inputs describes return content, not this tool's inputs.

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 resource — the current browser screen — and enumerates its contents (page/app state, ui_act actions with inputs, board components, active board). An agent can distinguish it from ui_act and show_board, though the boundary with show_board/describe_data is only implied, not spelled out.

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?

"Call it before ui_act, and to see what the user is looking at" gives a concrete precondition and a concrete use case. It stops short of naming when NOT to use it (e.g. vs show_board or describe_data), so it is clear context rather than full 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?

No annotations exist, so the description carries the full behavioral burden. It discloses sort order ('newest first'), which is genuinely useful, but says nothing about the default limit, whether results are paginated or capped, or what a board record contains—all behavior an agent must know before calling a list 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 short sentences, zero filler, with the core purpose and ordering front-loaded and the sibling routing placed second. Every clause earns its place.

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

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

With one optional parameter, no output schema, and no annotations, the surface area is small, so the terse description is close to adequate. Still, an agent cannot tell what the default page size is or how much data comes back, which matters for a listing call whose main risk is unbounded results.

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 single 'limit' parameter has only min/max bounds and no prose. The description never mentions limit at all—not its default value, not whether omitting it returns all boards or a capped page. The one parameter present is therefore undocumented in both places.

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 saved boards') plus the ordering ('newest first'), and explicitly distinguishes itself from the sibling show_board, which retrieves a single board by id. An agent can pick between the two without opening either schema.

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

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

The second sentence names the alternative (show_board with an id) and the condition that selects it, so the list-vs-retrieve fork is covered. It stops short of stating when not to use this (e.g., when an id is already known, skip listing), so it is clear context rather than a full when/when-not rule set.

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 well: read-only single SELECT, 5000-row cap, return shape (columns, row count, first rows), and that reusing a name replaces the existing dataset. It omits error behavior, timeouts, and permission requirements, but the core operational traits are 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?

Four tight sentences, front-loaded with the action and resource, then the compute guidance, return shape, limits, and replacement semantics. Nothing redundant or padded.

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 tool with no output schema and no annotations, the description covers return shape, row limits, and dataset-replacement behavior. Error handling and permission/scope expectations are the main missing pieces, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 67%, and the description adds real meaning beyond the schema for the two most important parameters: `name` becomes the dataset boards draw and its reuse replaces the old dataset; `sql` must be one read-only SELECT. preview_rows semantics are left to its schema description, which is adequate.

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 ('Run one read-only SQL SELECT against the app's SQLite database') plus the side effect ('keep the rows as a dataset named `name` that boards can draw'). The dataset-materialization purpose clearly separates it from schema-inspection siblings like describe_data, even without naming them.

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

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

Usage is implied: it is the tool for computing numbers in SQL rather than 'in your head', and read-only SELECT signals its scope. However, it never names describe_data as the alternative for discovering schema, nor states when not to use it, so routing guidance 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?

No annotations exist, so the description carries the full burden. It does disclose real behavior: 'id' replaces an existing board instead of adding one, 'note' places text at the top, 'title' replaces the recipe's title. However it says nothing about what happens with an unknown recipe name, whether the board is persisted/shown, or what the call returns.

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

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

Tight, front-loaded opening sentence followed by routing and per-parameter notes; nearly every clause carries information. It is dense to the point of being cryptic in places ('quote only figures you have read'), but no sentence is wasted.

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 and no annotations, and the tool creates/replaces persisted boards with a nested params object. The description covers the parameter semantics but omits error behavior for unknown recipe names and any indication of the result of a successful call, leaving a meaningful 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 coverage is only 20% (only 'id' is described inline), but the description compensates well: it explains name (the recipe), params ('its values, lists as arrays'), note (text at the top, only quote figures you have read), and title (replaces the recipe's). Only the nested param value constraints and the replace semantics interplay are left thin.

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: 'Draw a ready-made board in one call' from a named recipe, and contrasts it with the sibling 'draw', which 'makes new kinds of boards'. An agent can differentiate the two without opening schemas, though what a 'recipe' actually is remains implicit (a saved board template).

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

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

Explicit routing: 'Use one whenever it fits the question; draw makes new kinds of boards' names the alternative and the condition that selects it. It also covers the empty-state case ('No recipes yet: draw with save_as adds one'), though it never says when *not* to use a recipe beyond preferring draw for new board kinds.

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 must carry the behavior burden, and it does disclose the important parts: passing `id` mutates an existing board in place, and figures must be data-bound rather than typed into props. It does not say whether the supplied spec replaces or merges with an existing board, what is returned, or whether the write is reversible.

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 framing sentence is front-loaded and each subsequent sentence covers a distinct concern (spec shape, data binding rule, id semantics). The inline JSON fragment is dense but functional; nothing reads as padding, though the middle paragraph is heavier than it needs to be.

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

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

For a tool with an untyped free-form spec parameter, no annotations and no output schema, the description covers the essentials of constructing a spec and binding data. It still leaves the agent guessing about create-vs-render semantics, spec/id precedence, and the unused `title` parameter, so it is adequate rather than complete.

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 `spec` is declared as a bare `{}` with no structure, so the description's root/elements/props/children breakdown and the `$state` binding syntax add real value. However, `title` is never mentioned at all, and the component vocabulary is outsourced to `draw`'s documentation rather than restated, so the compensation is partial.

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 frames the tool concretely as the long-form counterpart of `draw` and states it consumes a self-authored json-render spec, with `id` alone reopening a saved board. It distinguishes itself from the sibling `draw` by capability ('for what draw cannot say'), though it never plainly says the board is rendered to the user, leaving that inference to the agent.

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 tells the agent when to reach for this instead of `draw` (when the hand-built spec is needed) and what the two `id` modes mean — reopen a saved board vs. change it in place. What's missing is any when-not guidance, e.g. what happens if both `spec` and `id` are supplied, or when to prefer `list_boards`/`get_screen` instead.

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 discloses that execution happens in the user's live browser and that the action's return value is passed through, but says nothing about side effects, reversibility, permissions, error behavior, or whether actions are destructive.

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 with the core purpose front-loaded and no filler. The final sentence ('Returns what the action returned') is mildly tautological but still communicates passthrough behavior.

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 generic dispatcher with a free-form input object, no annotations, and no output schema, the description covers discovery and return passthrough. It is missing safety, failure-mode, and validation context that an agent would need to invoke arbitrary actions confidently.

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%, so the schema documents neither the action string's valid values nor the shape of the arbitrary input object. The description compensates partially by saying get_screen lists actions and their inputs, establishing the action/input relationship, but it leaves the input structure entirely external and does not mention the 80-character action limit.

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: run one of the app's actions in the user's browser, with concrete examples (open a page, set a filter, select something). It distinguishes itself from get_screen by framing that sibling as the discovery mechanism, though 'one of the app's actions' remains somewhat abstract without knowing the app.

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?

Points the agent to get_screen for the list of actions and their inputs, which implies a prerequisite workflow. However, it never explicitly says to call get_screen first, gives no when-not conditions, and does not contrast with siblings like show_board or describe_data.

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