filing_markdown

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

With no annotations, the description carries the full burden. It discloses the read-only nature ('Read') and bounded output ('bounded'), but does not explain offset/refresh/ocr_mode behavior, pagination, or error cases. It adds some useful context but leaves significant behavioral traits unstated.

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 very short and front-loaded with no filler, which is positive. However, it is under-specified for a five-parameter tool—essential parameter semantics are missing, so conciseness comes at the cost of completeness.

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?

Given five parameters, no annotations, and zero schema description coverage, the description is too sparse. It does not explain offset, refresh, ocr_mode, or max_chars semantics, and only provides sibling guidance. The output schema may cover return values, but input behavior remains largely unexplained.

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 not name any of the five parameters. 'Bounded' hints at max_chars and 'Read' implies filing_id, but the semantics of offset, refresh, and ocr_mode are entirely unaddressed, so the description fails to compensate for the schema's lack of parameter descriptions.

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 clearly states a specific verb ('Read') and resource ('bounded Markdown page'), and further distinguishes itself from siblings by saying to prefer outline, search, or section tools. This makes the tool's purpose unmistakable and differentiates it from filing_read, filing_outline, etc.

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 phrase 'prefer outline, search, or section tools' gives explicit guidance to use alternatives when possible, implying this tool is a fallback for whole-page Markdown reads. It does not specify exact conditions (e.g., 'use when you need full text'), but it provides clear contextual direction.

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