delete_object

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

With no annotations present, the description carries the full load and does well: it discloses the stale-index guard ('the object's current name must equal expected_name, so a stale index ... deletes nothing'), the accepted path grammar, and the refused-target list. It omits whether the deletion is undoable or what permissions are required, which for a destructive operation is a meaningful remaining gap.

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?

Front-loaded with the verb and resource, then the accepted path grammar, then the refusal list, then the discovery hint, with an Args line at the end. Every sentence adds a distinct constraint; nothing restates the tool name or the schema.

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, so return-value detail is not required, and the description supplies the path grammar, the name-mismatch safety rule, and the negative scope that the 0%-coverage schema cannot. What's missing for a destructive, unannotated tool is the analysis_index semantics and any statement about reversibility or failure behavior beyond 'deletes nothing'.

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; it does so for two of three params, giving the exact accepted path strings ('Children[n]', 'Solution.Children[n]', 'Solution.SolutionInformation.Children[n]') and a precise contract for expected_name as a stale-index guard. The third parameter, analysis_index, appears only in the trailing Args list with no explanation of what it indexes or how it defaults.

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 (Delete) and resource (one object added to the analysis) and enumerates exactly which object kinds qualify: loads, supports, results, trackers, keyword snippets. It also names the sibling tools (list_scoping_targets, inspect_object) used for discovery, so an agent can place it precisely among the ~50 siblings.

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 directs the agent to 'Look first with list_scoping_targets or inspect_object' and enumerates the targets that are refused (analyses, analysis settings, Solution, mesh, contacts, named selections), which effectively tells the agent when not to use it. It does not spell out the condition that selects one sibling over the other beyond that one line, so it stops short of a full when/when-not/alternative rubric.

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