list_boards

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

With no annotations, the description carries the burden and does add real value: it discloses offset-based pagination, that fetch_all walks all pages, and warns about cost on large accounts. It omits permission/auth requirements and result ordering beyond the sort 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?

Three short sentences, front-loaded with the purpose, then pagination behavior, then parameter semantics. No filler; the warning about large accounts is brief and 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?

The output schema covers return values and the pagination behavior is disclosed, but for an 8-parameter tool at 0% schema coverage, the scoping parameters team_id and project_id are unexplained, leaving a meaningful gap for an agent filtering within a team or project.

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 description must compensate. It explains query, owner (with example values), sort (with example values) and fetch_all, but leaves limit, team_id and project_id entirely undocumented; offset/limit are only hinted at by "offset-paginated".

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 boards") plus the scope ("visible to the token"), which separates it from get_board and create_board in the sibling set. It doesn't explicitly name those siblings, so it falls short of a 5.

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?

Listing usage is implied by the name and the filter/sort options, but there is no explicit guidance on when to use this versus get_board, or when fetch_all is appropriate beyond a vague caution. The agent must infer the routing.

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