get_board

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

With no annotations, the description carries the full burden. It discloses that filling the agent parameter will prepend unread directed messages and mark them as delivered (a side effect), and explains the behavior when not filled. It also states it returns the Markdown file content. This is transparent about the conditional behavior, which is critical for a tool with an optional side-effect parameter.

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 description is a concise paragraph that front-loads the purpose and then explains the optional parameter. Each sentence adds value, and it avoids fluff. It's appropriately sized for a tool with two optional parameters.

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?

The description is complete for the main function, and the presence of an output schema likely covers the return format. However, the project parameter is left unexplained, which is a gap given the schema has no description. It also doesn't mention error conditions, but for a read operation with optional parameters, this may be acceptable. The missing project parameter explanation prevents a higher score.

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 description thoroughly explains the agent parameter, including its purpose and side effects. However, it does not mention the project parameter at all, despite schema coverage being 0%. Since there are two parameters and only one is explained, the description only partially compensates for the schema's lack of descriptions.

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 clearly states the tool reads the project's shared announcements (kanban) and returns the Markdown file content, listing the specific sections (claim area, shared decisions, latest changes). This is a specific verb-resource pair that distinguishes it from siblings like send_note or read_notes, making its purpose unambiguous.

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 explicitly says '开工前必看' (must read before starting work), providing a clear context for when to use it. It also explains that tasks sent via send_note are received here, which guides the agent to use this tool to check for assigned work. However, it does not explicitly state when not to use it or compare with alternatives like read_notes, though the context implies it.

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