get_metax_document

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

Even though readOnlyHint and idempotentHint already cover non-mutation, the description adds materially useful context: it reads a local SQLite index, never fetches URLs, never modifies the index, and treats retrieved text as untrusted. This is valuable security-relevant behavior beyond what the annotations state, and it does not contradict them.

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 compact and front-loaded: the first sentence states the operation, and the second delivers a dense, necessary safety warning. There is no filler or restatement of schema details.

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 simple read-only tool with rich annotations, an output schema, and defaults on optional parameters, the description covers the key extra facts an agent needs: local-only execution, no URL fetching, and untrusted retrieved text. The main gap is usage differentiation from sibling tools, which is already penalized under usage_guidelines.

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 0%, and the description does little to compensate. 'Bounded text window' loosely hints at offset/limit behavior, but document_id format, how the window is calculated, and the meaning of the offset/limit combination are not explained. Minimal value is added beyond the raw parameter names and defaults.

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 opens with a precise verb and resource: 'Read one indexed document and a bounded text window,' which clearly identifies the operation and scope. It does not explicitly name or contrast sibling tools like get_metax_section, so differentiation is partly left to the tool names, but the core purpose is unambiguous.

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?

There is no explicit guidance on when to use this tool versus search_metax_docs or get_metax_section. The safety note applies to the whole tool family rather than explaining selection criteria, leaving only the implied usage from 'Read one indexed document.'

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