diana_read_tb

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds substantive behavior: streaming for multi-GB files, truncation to the first max_rows rows inline, csv_path writing every matching row, and the caveat that non-converged steps are also written. The one gap is that it never says what happens if csv_path already exists or whether the file is overwritten.

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?

Well front-loaded: the two modes come first, then the Args block, then layout edge cases. It is long, but the length is driven by ten undocumented parameters and genuine DIANA format quirks rather than filler; the docstring-style Args formatting is slightly redundant given the schema already lists the names.

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 ten-parameter, zero-schema-coverage tool with a binary file format, the description covers selection semantics, output truncation, full-export escape hatch, and known layout quirks (COMBIN blank cells, MIN/MAX extreme columns, COOR/AXES additions). An output schema exists, so return shapes need not be restated.

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 carries the full burden and does: every one of the ten parameters is explained in plain terms, including which analysis type each of `step`/`load_case`/`mode` applies to, the Nodnr/Elmnr columns behind node_ids/element_ids, and a concrete example for the otherwise opaque `ids` map. This goes well beyond what the bare schema conveys.

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 ("Read a DIANA tabulated results file (.tb)") and immediately distinguishes two operating modes: index-only versus filtered result rows. An agent can separate it from diana_results_table or diana_read_out 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 says when to omit `result` (get an index) versus when to supply it (get matching rows), gives concrete example selectors, explains that omitting `step` yields the history over all steps, and warns to check diana_read_out / diana_job_status before trusting the last steps. That is real when/when-not guidance with named alternatives.

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