board_link

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

With no annotations, the description carries the full burden and does so richly: the URL value is burned on first use, the key carries no role, mailbox tools refuse it, the server rejects it anywhere except a board GET, and a role token is a write key no longer accepted by the board. It also discloses that calling again issues a new link and that revoke_board_access invalidates every viewing key for a channel.

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 is front-loaded well, but the text runs long and re-litigates the same viewing-key-vs-role-token contrast two or three times ('not an escalation', 'a DIFFERENT KIND of access', 'A role token is a write key'). Those restatements dilute an otherwise information-dense paragraph.

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 return values need little explanation, and the security/authorization model is covered thoroughly, which is the hard part of this tool. The remaining gap is the unaddressed input parameters, which the description should have covered given 0% schema description coverage.

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 the two parameters (label, channel), so the description is the only chance to explain them — and it never mentions either one. The phrase 'a channel's /board' loosely implies the channel parameter, but 'label' and its default 'board' are entirely unexplained, leaving the agent to guess.

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: 'Issue a READ-ONLY viewing link for a channel's /board — the page a HUMAN opens to watch the channel.' It explicitly distinguishes this from role tokens and names the sibling it pairs with (revoke_board_access), so an agent can tell it apart from send_message, pin_set, or list_channels 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?

Gives clear context for invocation ('when your user asks for the dashboard you can just hand them a link') and specifies who may call it (admin token for any channel, any role for its own). It names revoke_board_access as the invalidation alternative and explains that role tokens no longer work on the board, though it never states a crisp condition under which NOT to use this tool.

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