list_addable_objects

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

No annotations are provided, so the description carries the full burden, and it does disclose non-obvious behavior: acoustic/frequency-response/PSD/electromagnetic/optimisation items are silently omitted unless all_physics=true, and host='solution' additionally populates solution_information_methods. That default-filtering disclosure is exactly the kind of gotcha an agent needs. It stops short of stating side-effect-free read semantics, connection requirements, or behavior on invalid host values.

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 core purpose and the host semantics are front-loaded, and the Args line cleanly summarizes all four parameters. The opening sentence is grammatically tangled ('The Add* methods the analysis ... offers in this release'), which slows parsing slightly, but no sentence is redundant.

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?

With an output schema present, return-value explanation is unnecessary, and the description covers defaults, host branching, and physics filtering adequately for an exploratory list tool. The remaining gaps are the unexplained analysis_index parameter and the unstated assumption that a Mechanical connection already exists, which a sibling (connect_to_mechanical) implies is required.

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 compensate, and it largely does: host is given an explicit three-value enumeration absent from the schema, filter is qualified as case-insensitive text, and all_physics is explained in terms of what it re-includes. Only analysis_index is named without any meaning (presumably which analysis when host='analysis'), leaving one of four parameters uninterpretable.

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+resource: it enumerates the Add* methods available for an analysis, its Solution, or Solution Information, with concrete examples (loads, supports, conditions, results, probes, AddLSDYNAGeneralTracker). An agent can tell what it returns. It does not, however, distinguish itself from the closely related sibling list_binout_tracker_options, which overlaps with the solution_information path.

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?

'so a kind can be found without guessing' plus the explicit host-value semantics gives clear context for when to call it (discovering which Add* methods exist before adding one). The default-exclusion rule and the all_physics=true escape hatch are spelled out. Missing: any statement of when to prefer it over list_binout_tracker_options or inspect_object, and no prerequisite (e.g. connection) mentioned.

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