Read the preserved text of a link

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

The description adds significant behavioral context beyond the readOnlyHint annotation. It explains that long articles are paginated via offsets, how to continue reading ('pass the offset from the previous result to continue'), and what happens when no archive exists (error message + suggestion to use represerve_link). While it doesn't detail exact error formats or rate limits, the pagination and fallback behavior are well 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?

The description is three sentences, each with a distinct purpose: first sentence defines the primary function, second sentence clarifies what not to expect, third sentence explains pagination and fallback. Every sentence earns its place with no filler, and key information is front-loaded (the readable text purpose).

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 quite complete for a read tool with high schema coverage and a readOnlyHint annotation. It covers the core behavior, pagination, and fallback. However, it does not specify the return format (e.g., fields like text, metadata) or how to handle errors beyond the 'no readable archive' case. With no output schema, a bit more detail on the response structure would elevate it to a 5.

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 the baseline is 3. The description adds no specific parameter details beyond what the schema provides. The description does mention the offset parameter generically in the text ('Long articles are returned in slices — pass the offset from the previous result to continue'), which slightly reinforces its usage context but does not add new semantic meaning. Thus, it stays at the baseline.

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 uses specific verbs ('Returns the readable article text') and explicitly names the resource ('Linkwarden extracted and stored when it preserved the page'). It distinguishes this tool from sibling tools like 'get_link' by clarifying it serves only the readable text, not binary or raw markup archives. The sibling set includes many tools, but this description makes the tool's unique purpose clear.

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?

The description explicitly states when to use this tool: to read a saved bookmark without fetching the live site. It also says when not to use it for non-text formats ('the screenshot, PDF and single-file HTML archives are binary or raw markup and are not useful as text'). It mentions a fallback: 'If the link has no readable archive, the tool says so and represerve_link can create one,' which guides the agent to an alternative sibling tool.

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