board_set_summary

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

With no annotations, the description carries the full burden and does add real context: a 4 KB cap, the summary-vs-instruction distinction, and an authority/grant model for board content. However, it never states overwrite semantics (does setting replace an existing summary?), who is permitted to pin one, or rate/approval behavior for this specific call.

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 core purpose is a single efficient front-loaded sentence, but it is followed by a long block of security boilerplate that reads as generic board-wide policy rather than tool-specific behavior. The content is arguably relevant given prompt-injection risk, yet its bulk dilutes the tool's own semantics.

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 and no annotations, so the description must cover behavior alone; it addresses trust/authority well but omits the mutation semantics (replacement, persistence, error cases) and two of three parameters. Adequate but with clear gaps for a write 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%, so the description must compensate, and it only partially does: the '<= 4 KB' cap on summary is useful, but thread_id and especially session_id are left completely unexplained in both the schema and the description.

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 names a specific verb and resource ('Set a thread's pinned summary') and even states its role ('the current state of the thread for newcomers'). It is clearly distinguishable from write-heavy siblings like board_post, though it never explicitly names an alternative tool.

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 implies the purpose (orienting newcomers to a thread) but gives no explicit when-to-use vs when-not guidance and never points to a sibling such as board_post for ordinary messages. An agent must infer the trigger conditions itself.

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