snw_analyze_field_request

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

With zero annotations, the description must state whether the tool mutates state, the read-only nature, or side effects. It says it generates a plan and SQL but does not explicitly state that it only analyzes or does not execute changes, that it requires particular permissions, or what '不可变' implies for the caller. The phrase 'analyze' implies a read-like operation, but the important safety properties are left implicit.

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 a single front-loaded sentence with no filler. It names the operated resource, the work done, and the output artifacts economically. However, it is concise to the point of omission; stillh, for its small size, it is well-structured.

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?

The tool has seven parameters and a complex analysis task, yet the description gives almost no decision-relevant context for constructing the request. The presence of an output schema covers return-value shape, but an agent still lacks clues about why to use this specific tool, what required fields mean, and how parameters interact in the three-hop neighborhood and cardinality logic.

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, but it adds little. It maps the general tool behavior without explaining the meaning of the seven parameters: it does not indicate what request contains, how source_object and source_property scope the search, what aggregation is used for, what dialect values are recognized, or what collection_limit/howLimit controls.

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 states a specific operation ('解析字段来源', '校验基数', '生成不可变语义计划和 SQL') and a bounded scope ('三跳邻域内'). It is clear about the resource and deliverables, and the ```execute```/```create``` siblings are different enough that a reader can likely tell this is the analysis step, but it does not name any sibling explicitly.

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?

There is no explicit guidance about when to call this tool instead of the siblings, when it is not appropriate, or what steps should precede it. The only signal is the name 'analyze', which suggests it precedes execution or creation, but the description does not say 'use before executing' or exclude cases like direct execution.

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