ui_tree

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

With no annotations, the description carries the full burden, and it does so thoroughly: it discloses default profile behavior, RAG auto-enablement logic, absence of depth limits, filter-dependent output shape changes, and side effects such as include_data potentially calling ПолучитьПредставлениеДанных() for many nodes. It also explains the auto/resource delivery behavior and what resource responses contain. This exceeds the transparency typically expected from a tool definition.

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 long, but it earns its length given 19 parameters and complex delivery behavior. It is front-loaded with the core purposeton, then organized into navigable chunks: profiles and filters, targeted alternatives, format/delivery modes, and resource inspection follow-ups. Every section contributes actionable information with no filler.

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 high-complexity tool with no output schema and 19 parameters, the description covers the critical decision points: default profile, when results are flat vs nested, when data enrichment is risky, how delivery thresholds work, and how to inspect resource-backed snapshots. The few unaddressed parameters are minor relative to the operational picture an agent needs.

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 meaningfully explains profile, fields, include_rag_types, parent_name, include_hidden, include_data, format, and delivery, including default values and consequences. However, several parameters (compact, group_mode, session_id, rag_snapshot, command_panels, include_timings, preview_max_nodes, include_command_panels) receive no explanation, so coverage is not complete.

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?

Opens with a specific verb-resource pair: 'Return a serialized snapshot of the active 1C UI tree.' It then differentiates itself from sibling tools by explicitly pointing to targeted alternatives: field_value_text for one field, table_rows for tables, tabular_document_text/save for tabular documents, and search_objects/find_object for locating a single control. An agent can clearly determine what this tool does and when it is not the right choice.

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?

Provides explicit when-to-use and when-not-to-use guidance, including 'Prefer targeted tools for data' with named alternatives, and 'For finding one control, prefer search_objects/find_object.' It also warns against enabling include_data casually on large forms and explains when to force resource delivery for large/verbose diagnostics. This is direct usage routing, not vague generalities.

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