Find ACS symbol

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

No annotations are provided, but the description gives reasonable behavioral context by explaining the input/output nature: it resolves identifiers to symbol details. However, it does not explicitly state that it is a read-only lookup or mention any side effects, permissions, or limitations. The example aids understanding.

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 two sentences long, front-loads the core purpose, and includes a clarifying example. Every sentence adds value without unnecessary detail.

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 the tool's simplicity, the description is largely complete: it explains inputs (script number or name), outputs (name, number, file:line), and provides an example. However, it does not document the 'dir' parameter or any error cases. Since no output schema exists, the description compensates adequately by describing the return value structure, earning a high score.

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?

The description explains the 'ref' parameter implicitly by stating it resolves a script number or name. However, the 'dir' parameter is not mentioned at all. With 0% schema description coverage, the description adds some meaning for one parameter but fails to cover the optional one. Baseline for 0 params would be 4, but with two params this is only partial.

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 clearly states that the tool resolves a script number or name to symbol information (name, number, file:line) and gives a concrete example (turning 'script 1017' into a source location). This distinguishes it from sibling tools like list_scripts (which lists names) and profile_scripts (which profiles).

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?

The description implies usage when one has a script number or name and needs the corresponding source location, but it does not explicitly state when to use this tool versus alternatives (e.g., list_scripts for listing only, or profile_scripts for profiling). No exclusion criteria are provided.

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