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

Annotations already establish readOnly, idempotent and non-destructive, so the bar is lower; the description still adds that it operates on 'the linked account' and returns ids, titles and URLs for citation, which tells the agent the output shape and its intended use. No result limits or pagination are disclosed.

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 purpose, then return shape, then the fetch handoff and edge case. No restatement of the name and no filler.

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?

For a single-parameter read tool with no output schema, the definition covers purpose, result fields, and the empty-query case — enough to call it correctly. The missing piece is any indication of result count limits or ranking behavior.

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% and the only parameter is a bare 'string' named Query, so the description carries the full burden — and it does: query is 'a question or keywords', and the empty-string behavior is specified. That is meaningful semantics added beyond the schema, though no format or length guidance is given.

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 set: it searches the linked account's Linko notes and saved resources. The scope (both content types) implicitly covers the ground of search_notes and search_resources, but never names those siblings, so an agent must infer the distinction itself.

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?

Explicitly routes reading of an individual item to `fetch` and documents the edge case that an empty query returns recent items. It does not address when to prefer the sibling tools search_notes, search_resources, linko_search or get_note, leaving some ambiguity in a crowded search namespace.

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