mathematica_run

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

With no annotations, the description must carry the full behavioral burden, and it does disclose the execution sequence (precheck → execute → export → re-run → reconcile → deliver), which tells the agent this is a long, composite, stateful operation. It says nothing about side effects (files written to out_dir, overwrite semantics), expected duration (timeout defaults to 900s, frontend to 240s), or failure/partial-success behavior, which are the traits that matter most for a pipeline of this weight.

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?

A single front-loaded sentence with a colon-separated stage list — dense and waste-free. Its brevity is appropriate structurally, though it is concise to the point of under-specification for an 11-parameter tool (that cost is charged under contextual completeness).

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 heavy 11-parameter pipeline with no annotations and no output schema, the definition omits nearly everything an agent needs: what task_path points to, what the run produces, whether it is safe/idempotent, and how long it takes. The stage enumeration gives a rough mental model but is far short of sufficient.

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?

Eleven parameters with 0% schema description coverage, and the description explains none of them. Flags like dry_run, no_rerun, allow_draft, allow_external, no_frontend and overwrite are semantically loaded and cannot be guessed from their names alone, especially the safety-relevant ones. This is a severe compensation failure at the lowest coverage tier.

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 concrete action (run the full pipeline) and enumerates the six stages: precheck, native execution, export, reopen-and-recompute, reconciliation, delivery. This implicitly distinguishes it from the single-step siblings (mathematica_doctor, mathematica_export, mathematica_verify), though it never names them. Clear purpose, but sibling differentiation is left to inference.

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 word '完整' (full/complete) hints that this is the end-to-end option versus the individual stage tools, which is an implied routing signal. However, there is no explicit statement of when to choose this over mathematica_build + mathematica_export + mathematica_verify, and no prerequisites or exclusions are given.

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