Bridge connection and readiness / 连接与就绪状态

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: diagnostics return an unavailable connection as data, a successful call does not mean the bridge is connected or editable, the state can change between check and command, and operations take no arguments. These are non-obvious traits an agent could otherwise misread.

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 core purpose and the starting operation, then routing, then behavioral caveats. It is dense and somewhat long for a 1-parameter tool, and the bilingual parenthetical duplicates add length, but every sentence carries operative information.

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?

Although an output schema exists (so return fields need not be enumerated), the description still explains return semantics (structured state, suggested next actions, unavailable connection as data) and tells the agent to read connected/status and capability fields. Nothing needed to call it correctly 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 request schema documents the operation discriminator and each branch. The description adds one useful clarification beyond the schema – 'Supply request.operation only; these diagnostic operations have no arguments' – which preempts an agent over-filling the nested request.

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 (diagnose) and resource (QiaoTong connection, active model state, edit readiness) and immediately contrasts itself with engineering operations. The description also names the three sub-operations, so an agent can distinguish inspect_bridge from edit_* / query_* siblings 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?

Explicit when-to-use ('before choosing an engineering operation', 'start with check_qiaotong_connection') and explicit when-not ('these are diagnostics, not requests to open a model, clear results, prepare edits or switch stages'). It routes to named alternatives: query_model for engineering records and manage_model_files to open/save a project.

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