diana_load_results

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

With no annotations supplied, the description carries the full burden and does well: it discloses that this is a mutation (attaching results to an analysis), that replace is destructive ('clear results already attached to the analysis first'), and that the underlying loadResults call refuses without it. It also names the return payload. It stops short of stating preconditions such as the project needing to be open or the analysis needing to exist, which is the remaining gap for a no-annotation mutation 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?

The first sentence front-loads purpose and destination, the second sentence covers mode selection, and the third covers the return value that feeds diana_plot_result. The trailing 'Args:' block restates job_id and dnb_path already covered in prose, a small redundancy, but it does add the analysis default and the replace semantics.

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?

An output schema exists, yet the description still adds workflow value by stating that the returned cases and labels are what diana_plot_result accepts. For a four-parameter mutation tool with no annotations, the definition covers invocation modes, the destructive flag, and the return contract; only environmental preconditions (open project, valid analysis target) 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?

Schema description coverage is 0%, so the description must define all four parameters, and it does: job_id (a finished job from diana_solve), dnb_path (absolute path of a .dnb file, used instead of job_id), analysis (with its default being the job's analysis), and replace (its clearing behavior). What is missing is format/syntax detail for dnb_path beyond 'absolute' and any constraint on what a valid analysis identifier looks like.

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 resource ('Load solver results (.dnb) into an analysis of the open DianaIE project') plus the downstream intent ('to plot them there'). It also positions the tool between its two natural siblings, diana_solve as the producer of job_id and diana_plot_result as the consumer of the returned labels, so an agent can place it in the workflow without opening any schema.

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 presents the two invocation modes: 'Pass a job id from diana_solve (file and analysis are known), or dnb_path together with analysis.' It also gives a real when-to-use condition for the replace flag ('loadResults refuses otherwise'), which tells the agent the call will fail if existing results are present and replace is false.

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