uplus_generate_experiment_report

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

With no annotations, the description carries full disclosure burden. It does add genuinely useful behavior: the output_path is sandboxed to allowed directories with config/env overrides. But it omits whether an existing file is overwritten, whether directories are created, whether a template/login context is required, and what is returned on success or failure.

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 short paragraphs, front-loaded with the core action, then the constraint. No filler. The parenthetical config detail is slightly dense but still earns its place as an escape hatch for the path restriction.

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 six-parameter, four-required file-writing tool with no annotations and no output schema, the description says nothing about return values, overwrite behavior, or the expected form of the free-text content/purpose fields. An agent could not call this correctly on the first try without guessing.

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 six parameters, so the description must compensate. It explains only output_path semantics; title, purpose, content, student_id, and student_name are completely undescribed — notably whether content/purpose are plain text, Markdown, or structured sections expected in the report body.

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 artifact: 'Generate a standard experiment report .docx file.' This distinguishes it implicitly from the sibling uplus_submit_experiment_report (which submits rather than generates). It stops short of explicitly naming that sibling or clarifying the relationship, so it is clear but not fully differentiated.

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?

There is no guidance on when to use this instead of uplus_read_experiment_detail or uplus_submit_experiment_report, nor any stated prerequisites (does it require login or an inspected experiment first?). The only operative guidance is a path restriction, which is a constraint rather than usage context.

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