read_files

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

With no annotations, the description carries the full burden and does disclose key behavior beyond the name: local processing with no disk download, OCR handling for scanned PDFs, and a concrete side effect (writing text/<id>.txt into the chat folder). It does not cover failure modes for unsupported formats, size limits, permissions, or whether overwrites occur, which keeps it short of a 5.

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 verb and resource are front-loaded, and every clause adds information (format list, no-download guarantee, OCR note, output path, default behavior). The long format enumeration is dense but functional; the trailing fragment after the dash is slightly abrupt but readable.

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 two-parameter file-reading tool that writes output artifacts, the description covers formats, OCR, output location, and the no-ids default, and an output schema exists so return values need not be explained. Missing items are edge-case behavior (unreadable/unsupported files, errors, overwrite semantics), which are secondary but not trivial for a writing tool.

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%, so the description must compensate. It fully explains 'ids' via the default rule (all unread files of the chat when omitted), but 'chat' — the required parameter — is only alluded to via 'папке чата' without stating its expected format (id vs name). Half the parameters are clarified, half are not.

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 gives a specific verb ('Читает текст файлов' – reads file text) plus an enumerated resource scope (txt, md, csv, html, pdf, doc, docx, rtf, xlsx, pptx, images) and states where the result goes (text/<id>.txt in the chat folder). The clause 'без скачивания на диск' (no downloading to disk) implicitly distinguishes it from fetch_media/fetch_large_file siblings, so an agent can tell what this tool does versus the media-fetching ones without opening the schema.

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 final sentence 'Без ids — все непрочитанные файлы чата' gives a clear default usage mode (batch unread files when ids are omitted). It supplies context for when to call it, but never explicitly names alternatives like ocr_photos, describe_media, or transcribe, nor excludes cases where those siblings are the better choice.

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