pathway_project

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

Goes well beyond annotations: discloses the return payload (node table plus reversely-moving adjacent pairs), writes JSON-LD and intermediate mzTab-M to reports/pathway/<run_id>/, the backend selection order (remote mslipidmapper_api_url server first, local RScript fallback, reported in the 'backend' return field), and the statistics used (Welch on log2(x+1), BH per pathway×scope type, log2fc sign convention). This is unusually rich behavioral context for a mutating, open-world tool.

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?

Front-loaded statement of action, then a return-value sentence, then a structured parameter bullet list where each bullet earns its place. Dense but well organized; the statistics paragraph could be trimmed slightly but is not filler.

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 9-parameter, no-output-schema, mutating tool this is nearly complete: return shape, side-effect files, backend behavior, and significance methodology are all covered. Only q_threshold's meaning and the exact effect of labels on output naming are left implicit.

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 coverage the description carries the load and does well: it defines source semantics, the differing form of group_a/group_b per source (Class ID/factor token vs sample-name list), the pathways values (remodeling/ceramide/global), acyl_chains format example, and aggregation options plus its meaning. q_threshold is never explained in the description (the BH note implies it but does not define it), which is the one clear 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?

Specific verb + resource: projects preprocessed lipid data onto MSLipidMapper pathways and compares two groups. It also names pathway_plot as the sibling that produces figures, so the agent can distinguish the two without opening schemas.

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?

Explicitly states the prerequisite chain (source=arf requires arf_preprocess, source=dataset requires dataset_preprocess), the auto-resolution order with the missing_state fallback, and the eligibility constraint (only for lipid assays with record_objective assay_kind=lipid). Alternatives for plotting are named.

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