Запрос JSONata

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds useful context beyond them: root $ is the manifest, the return is the raw expression result, and JSONata errors arrive as S0xxx/T0xxx with a correction hint. It does not say anything about result size limits or expression cost, which is the only remaining behavioural 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?

Front-loaded with the usage cue, then return/error behaviour, then the next-step alternatives, with the endpoint as a closing tag. Every clause earns its place and the ordering matches how an agent decides-and-calls.

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 one-parameter, annotation-rich tool with no output schema, the description covers intent, the root-context an agent needs to author a query, error signalling, and the sibling routing. Nothing required for a correct first call is missing.

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 coverage is 100% and the single parameter is documented (including the auto-parenthesisation behaviour), so the baseline applies. The description nevertheless adds genuinely new semantics — that '$' resolves to the model manifest — which an agent needs in order to write a valid expression.

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?

States a specific verb and resource ('произвольный JSONata по манифесту модели') and immediately distinguishes itself from query_dataset, describe_query_result and get_entity/list_entities. An agent can tell exactly what this tool does and does not do 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?

Explicitly framed as 'Когда вызывать' with the selecting condition (arbitrary JSONata over the manifest), plus named alternatives with their own conditions (query_dataset for datasets, describe_query_result for exploring result shape, get_entity/list_entities for typical selections). Both directions — when to use and when not to — are covered.

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