publish_results

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

The annotations already declare a destructive write, and the description adds meaningful behavior beyond them: it backs up an existing .dat, refuses stale results and custom DataSet paths, and requires GUI reload to view changes. This gives the agent a clear picture of side effects and failure conditions.

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 four compact sentences, front-loads the main operation, then lists prerequisites and side effects. Every sentence adds useful context without repetition.

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?

Given the output schema and annotations, the description covers the write behavior, backup behavior, rejection modes, and post-action requirement well. The remaining gap is exact parameter mapping, which matters because the schema itself provides no descriptions.

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 all three required parameters lack structured explanations. The description implies mappings for the .dat path, dataset, and current schematic hash, but it never names the parameters or clarifies expected formats, leaving path vs dataset_path ambiguous.

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 gives a specific verb and resource: save the bridge's verified run dataset to the schematic's .dat path for GUI plots. It distinguishes this operation from read_results and save_schematic by naming the dataset-publishing outcome and GUI-plot purpose.

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 states clear prerequisites (matching run provenance and current schematic hash), exclusions (refuses stale results and custom DataSet paths), and the context for use (GUI plots, then reload in the GUI). It does not name an alternative sibling tool, but the when-to-use conditions are strong.

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