Plecs Capture

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

No annotations, so the description carries the full burden. It discloses the inline-vs-file output modes and the sequencing prerequisite, but says nothing about what happens when save_to points at an existing file, why overwrite exists, whether the operation is read-only, or what is returned in file mode.

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 compact sentences that front-load the core action and the output-mode choice. Efficient with no filler; slightly terse given how much parameter surface is left undocumented.

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?

A 6-parameter tool with no annotations, no output schema, and 0% schema description coverage needs substantially more from the description. Key selection-relevant facts (scope_path vs. analysis_name precedence, overwrite semantics, return shape) are absent.

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 0% across 6 parameters. The description explains inline, save_to, and analysis_name (including its path convention), but leaves model_name, scope_path, and overwrite completely unexplained, so it only partially compensates for the coverage gap.

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?

States a specific verb and resource: 'Render a scope or analysis plot as a PNG', with the two output modes (inline image vs. file via save_to). It is clear what the tool produces, though it never distinguishes itself from the closely-related sibling plecs_plot.

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?

Adds a real prerequisite ('run the analysis first') and explains what analysis_name maps to, which helps the agent pick the right input. But there is no guidance on when to choose this vs. plecs_plot or plecs_scope, nor any exclusions.

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