Get a NEON document

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: text extraction is 'extracted in memory and paged by character offset', which warns the agent that large text is not returned all at once and must be paged. It also discloses the 'No token' auth requirement and the optional PDF dependency (neon-mcp[pdf]) via the schema. It does not mention rate limits or failure modes, but the in-memory paging behavior is a meaningful disclosure.

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 sentences with no filler. The first sentence front-loads the core purpose and return fields, the second states the key constraint (no token) and the optional text mode, and the third gives actionable next steps. Every sentence earns its place and the structure is easy to scan.

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 read-only metadata tool with an output schema, the description is nearly complete. It covers the two lookup modes, the optional text extraction, pagination, and the sibling download tool. The only missing context is a brief note on when to use spec_number vs url (e.g., which is preferred), and the fact that extract_text requires the optional pdf extra is only in the schema, not the description. These are minor gaps given the output schema and annotations.

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 71%, so the schema already documents most parameters. The description adds meaning by explaining the relationship between spec_number and url (two alternative lookup keys), and by clarifying that char_offset is the pagination mechanism for extracted text. It also ties extract_text to the paging behavior. The only minor gap is that the description doesn't explicitly explain how pages interacts with extract_text, but the schema covers the format examples.

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 states a specific verb ('Get') and resource ('Metadata of a NEON document'), and enumerates the exact fields returned (type, size, file name, description, products that reference it). It also distinguishes the optional text-extraction mode from the metadata mode, and names the sibling tool (neon_download_files) it is not. This clearly differentiates it from siblings like neon_get_product or neon_get_citation.

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 says 'No token' (no authentication needed), and gives a concrete next-step routing: 'Next: page through text with char_offset, or call neon_download_files(spec_number=...) on stdio.' This tells the agent when to use this tool versus the download sibling, and how to continue after the first call. It also implies the two lookup modes (by spec number or documents URL) without needing to open the schema.

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