Symbol Source (L2)

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

Annotations already indicate readOnly and non-destructive. The description adds 'EXACT' but lacks details on behavior like whether the source is fetched from cache or live, size limits, or formatting. It also inconsistently mentions 'source and contract' while the view parameter includes 'reference' as a third option, which could confuse agents.

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 extremely concise (one phrase), which is efficient but sacrifices clarity. It lacks structure such as separating purpose from behavior and usage. While no words are wasted, the brevity results in omission of critical information needed for correct tool invocation.

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 has 4 parameters and no output schema, and there are many sibling tools, the description is insufficient to guide an agent on correct usage. It does not explain return format, error conditions, or relationship to similar tools like file.contracts. An agent would lack context on when and how to use the view parameter.

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?

With 75% schema coverage, the schema itself describes parameters symbol, filePath, repository_id. The description adds no additional meaning for parameters; it doesn't explain the view parameter's options or what 'contract' versus 'source' versus 'reference' means in this context. The 'EXACT source' phrase is ambiguous regarding parameter usage.

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 identifies the tool returns the exact full symbol source and contract scoped to a repository. 'EXACT' emphasizes precision, and 'repository-scoped' sets scope. However, it doesn't explicitly state the action verb (get/retrieve), but the context implies reading. Differentiates from siblings like symbol.context (context vs full source).

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 usage guidelines are provided. The description does not indicate when to choose this tool over alternatives like symbol.context or file.contracts. No scenario or prerequisite information is given.

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