PDF: paragraph around the selection

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

readOnlyHint=true already establishes a safe read, so the description's job is to add beyond that — it does by disclosing what comes back (the paragraph, `neighbours` paragraphs before/after, and line numbers) and that `text` can substitute for the live mouse selection. It does not cover fallback behavior when no selection exists, but the added context is genuine.

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?

Front-loaded and short, but the opening sentence 'The paragraph around the user's mouse selection' is a near-verbatim restatement of the title and is then repeated at the start of the longer second sentence. One sentence of duplication is wasted space.

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?

An output schema exists, so return values need no prose explanation, and the safety profile is covered by annotations. Still, with four parameters at 0% schema description coverage and no clarification of what `page` or `path` do (especially with zero required parameters), an agent cannot fully infer how to target the correct document.

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 schema documents nothing and the description must compensate. It explains `neighbours` (paragraphs before and after) and `text` (an alternative to the live selection), covering two of four parameters, but leaves `page` and `path` completely undefined.

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 names a precise resource — the paragraph containing the user's mouse selection, plus neighbouring paragraphs and line numbers. It implicitly contrasts with page-level retrieval via 'without reading the whole page', but never names the distinction against siblings like get_selection or page_text explicitly.

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 gives a rationale for use ('so you can see what they are pointing at without reading the whole page'), which implies 'use when you need around-the-selection context cheaply'. However there is no explicit guidance on when to prefer get_selection or page_text instead, and no stated preconditions.

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