pathway_plot

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

Beyond annotations, it discloses important behavior: output is a PDF plus a PNG shown in chat, each image costs about 2,400 image tokens, and execution tries a lab server first before falling back to local R with headless Chromium and unpkg access. It does not describe error behavior or authentication, but it adds substantial context.

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 front-loaded with the core action and uses bullets to make parameter guidance scannable. The dependency note is relevant, though the entry is denser than ideal and mixes several operational facts into one block.

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 tool with no output schema and 0% schema description coverage, the description provides purpose, parameter semantics, output format, token cost, and runtime dependencies. It could be more complete about where the PDF is saved or what errors look like, but it is adequate for correct invocation.

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%, so the description must carry parameter meaning, and it does: run_id defaults to the latest run, pathways are chosen from the run and default to all, and plot_type is one of dot, box, or violin with group ordering noted. It does not describe run_id format or valid pathway naming conventions, but it covers all three parameters well.

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 states a specific verb and resource: it draws a pathway_project run as a pathway diagram (PDF) and displays it as a PNG in chat. This is clear enough to distinguish it from the project-management sibling pathway_project, but it does not explicitly contrast itself with other plotting tools.

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?

It gives useful operational guidance such as run_id defaulting to the latest run and pathways defaulting to all pathways in that run. However, it does not explicitly say when to choose this tool over alternatives such as save_figure or other plot tools.

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