Поиск документов

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds real behavioral context beyond that. It discloses that number matching is fuzzy ("33" resolves to 0000-000033 and also to a counterparty's incoming invoice number) and that 1C numbering resets annually, so a single number may hit documents from several years — a non-obvious trait that changes how an agent should query. It does not mention result truncation or ordering, which is a minor remaining gap.

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 purpose is front-loaded in the first clause, followed by routing rules and then the numbering caveat, and each sentence contributes distinct information. It is dense but well ordered; the one weak spot is that the kind enumeration at the start partially restates the enum already in the schema.

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 an 11-parameter, all-optional search tool with an output schema and read-only annotations, the description covers the essential decision points: type selection, the numbering pitfall, and the default scope. It omits pagination/limit behavior and what happens if kind and entitySet are both supplied, but these are secondary given full schema coverage and a defined output schema.

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 100% and every parameter is documented in the schema, so the baseline is 3. The description does add genuine meaning on top: the human-vs-technical number semantics, the kind/entitySet mutual exclusivity, and the note that entitySet is the only route for rare document types. That pushes toward the upper end of 3, but much of the parameter guidance duplicates what the schema already states.

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 specific verb and resource ("Ищет документы") and immediately enumerates the filterable dimensions: period, number, counterparty, organization, posting status, and amount. It distinguishes the two type-selection modes (kind vs. entitySet from list_entities) and defines the default fallback across all main document types, so an agent can tell this apart from read.document.get_document without opening a 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?

It gives explicit routing rules: use kind for common categories, entitySet for rare types like payroll or regulatory operations, and neither for a broad sweep, reinforced with example phrasings ("все документы за 10 сентября", "документ №33"). It also advises narrowing by period when searching by number. It stops short of naming a sibling such as get_document for single-record retrieval or analytics tools for aggregates, so one exclusion-style comparison is missing.

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