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

Annotations already declare readOnlyHint/openWorldHint/no-destructive, so safety is covered. The description adds non-obvious context the annotations do not: the search spans every board plus the open one, default sort is last viewed, and the call requires a Cotlet API key with app access. Return format/pagination is still unspecified.

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, scope and the follow-up tool are front-loaded, and the auth note is a useful closer. However, 'like the in-app search' and 'as the Search icon in Milanote does' convey the same idea twice, costing a little tightness.

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?

With no output schema, the description covers what to expect (hits sorted by last viewed/modified) and how to proceed on a hit (get_board). It stops short of describing the shape of a result item or result limits, but is otherwise sufficient for a read-only search 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 100%, so both query and sort are already documented, including the enum and default. The line 'Results are sorted by last viewed unless you ask for last modified' restates the schema default rather than adding syntax or format detail, so the baseline 3 is correct.

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 (find notes and boards by text) plus the scope (across all your boards, including the one currently open), which separates it from list_boards and get_board. It even names the follow-up sibling, so an agent can pick this tool 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?

Tells the agent when this applies (text search across all boards, matching in-app search behavior) and routes to get_board to read a hit's cards. It does not explicitly exclude the alternative list_boards for browsing, but the search-vs-browse distinction is clear from context.

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