get_workspace_state

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

With no annotations, the description carries the burden and does well: it explains the auth flow (browser-based pairing, the bridge never sees credentials), the response type (text), and interpretation details like SQL/draw cells reporting a pane view and mode. It stops short of rate limits or failure modes beyond the pairing case.

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

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

Dense but nearly every sentence carries weight, and the field-by-field view/mode semantics are actionable. Slight deduction because it opens with the failure/pairing branch rather than the tool's own purpose, so the primary function is not fully front-loaded.

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

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

No output schema exists, yet the description compensates by describing the returned context and the view/mode/result_height semantics for cell types. For a zero-required-param read tool this is close to complete, with only minor gaps around error behavior aside from pairing.

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% for the single boolean, so the description must compensate. It does: 'Pass include_user_events=true to also receive the digest of edits the user made since your last fetch' explains both the toggle and the delta semantics beyond the schema's bare boolean.

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 ('Return the current workspace + notebook context as text') and enumerates what that context includes: active notebook, cells, layout mode, chart configs, last-run statuses. It also distinguishes itself from siblings by noting the edit digest lives in get_recent_user_actions, so an agent can route 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?

Gives an explicit usage rule ('call get_workspace_state at the start of every notebook turn'), a recovery branch for BRIDGE_NOT_PAIRED that names the alternative tool (get_pairing_credentials), and the condition that selects get_recent_user_actions. When-to-use and alternatives are both stated.

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