plc_analyze_symbol

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral information beyond that: results are paginated, may carry diagnostics, and coverage is explicitly flagged as incomplete, which warns the agent that absence of a reference is not proof of absence. It does not mention permission requirements or the meaning of transaction_id, but the added context is meaningful for a read-only tool.

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?

Two sentences, front-loaded with the core action and immediately followed by the output/limitation contract. No filler. The only mild cost is dense domain shorthand ('ST/LD') that assumes PLC familiarity, but nothing is redundant.

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?

An output schema exists, so return structure need not be spelled out, though the description helpfully flags diagnostics and incomplete coverage. For a 5-parameter analysis tool with 40% schema coverage, the gaps around variable_id and transaction_id semantics are the main incompleteness, along with no guidance relative to plc_find_references.

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 only 40%, so the description needs to compensate and largely does not. It implies pagination through 'paginated references', but says nothing about variable_id (the declaration being resolved), project_id, or transaction_id, and does not clarify whether transaction_id pins the analysis to a snapshot. The resolution dimensions listed (scope, aliases, members/parameters) describe the analysis, not the inputs.

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 names a specific verb and resource: 'resolve one declaration's observed ST/LD references by scope, external aliases and known members/parameters.' That is far more precise than a generic 'analyze symbol' restatement, and it scopes the operation to a single declaration. It stops short of distinguishing itself from the sibling plc_find_references, so an agent still has to guess which of the two to pick.

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?

'no full type checker or HMI/library analysis' is a genuine boundary statement telling the agent what this will not do, which implies the cases where a deeper analysis is needed. However, there is no positive when-to-use condition and no explicit routing to or away from plc_find_references, so the choice between sibling reference tools remains implied rather than stated.

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