Structural responses and tendon results / 结构响应与钢束结果

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds real behavioral context: 'These calls do not solve, refresh or certify result freshness', an empty response may mean an absent case or inactive tendon rather than zero, paged operations slice locally after backend retrieval with a next-offset hint, and 'Envelopes do not represent simultaneous loads'.

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 purpose and organized into scannable bullets plus a concrete example request, which is appropriate for a six-branch dispatcher. It is long and repeats some per-branch details already in the schema descriptions, so a little of the text does not earn its place beyond structured fields.

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?

Given a six-way discriminated union and an existing output schema, the description covers preconditions, empty-result interpretation, pagination behavior and sibling routing adequately. Minor gaps remain around unit conventions and per-operation availability nuances, which live only in the branch schemas.

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%, so the baseline is 3, but the description adds cross-cutting parameter meaning: stage_id=-1/0/positive semantics, the ID namespace rule (node vs element by result_type) and the concrete worked example request. It also warns that full case identifiers must come from QiaoTong results/UI rather than derived from combination codes, which is operational guidance beyond field-level docs.

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 ('Retrieve numerical structural responses from the bridge's result data') and then enumerates the six operation families with what each returns (analysis results, special/modal results, live-load envelopes, tendon loss/position/length). It explicitly distinguishes itself from siblings ('Use query_model for saved definitions, manage_checks for code-check results and view_model for plots'), so an agent can route without opening each 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?

States the precondition ('Use after analyze_model has completed the relevant solve') and gives per-branch selection rules, e.g. get_live_load_results 'request one maximum or minimum envelope extreme' and tendon geometry available pre-solve 'depends on the bridge'. Altern</br>atives are named with the condition that selects them (query_model/manage_checks/view_model), which is exactly when-to-use guidance.

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