pinescript-mcp

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

Annotations already indicate this is a read-only, idempotent, closed-world operation. The description adds valuable context beyond annotations: it explains the navigation purpose, specifies the header level returned (##), clarifies what's omitted (### subsections), and mentions typical file sizes (50-115 sections). No contradiction with annotations exists.

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 efficiently structured: first sentence states the core purpose, second provides usage guidance, third highlights specific use cases, and the Args/Returns sections clearly document parameters and output. Every sentence adds value with zero waste, and key information is front-loaded.

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?

For a simple read-only tool with good annotations and one parameter, the description is nearly complete. It explains purpose, usage, parameter semantics, and output behavior. The only minor gap is lack of explicit mention of error cases (e.g., what happens if the file doesn't exist), but given the annotations and straightforward nature, this is acceptable.

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 0% schema description coverage for the single parameter 'path', the description fully compensates by providing clear semantics: it explains 'path' as 'Documentation file path' and gives a concrete example ('e.g., "reference/functions/ta.md"'). This adds essential meaning beyond the bare schema type (string).

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 the specific action ('List all section headers') and resource ('in a doc file'), distinguishing it from siblings like list_docs (which lists documents) and get_section (which reads content). It explicitly mentions the scope ('top-level section headers (## level)') and what's excluded ('Subsections (###) are omitted').

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 provides explicit guidance on when to use this tool ('Use before get_section() to find the right header') and when not to use it ('Subsections (###) are omitted'). It also mentions specific use cases ('Especially useful for large files...') and references an alternative tool (get_section with include_children=True for subsections).

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