triz_expand_hierarchy

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

With no annotations, the description carries the full burden and does so: it states what is preserved (inner costs, feasibility, states, transitions, standalone inner flows), what the caller must supply (explicit routes for parent flow occurrences, checked boundary connections, media mappings), what is opt-in (budget/weights/contradictions policies), and the fail-closed behavior on product-identity changes.

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 text is front-loaded with the core operation, then layers preservation, requirements, policies and ordering. Every sentence carries distinct information, though several are densely packed with domain jargon that an unfamiliar agent may need to unpack.

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 complex five-parameter mutation tool with no annotations and no output schema, the description covers return value ('a typed model and fresh box, wire and flow id maps'), invariants, required inputs and failure mode. Only the precise shape of routes and the full set of validation failures remain undocumented.

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 only 20% (essentially just `box`), so the description must compensate, and it does explain the roles of `routes` (parent flow occurrences), `media` (explicit mappings) and `policies` (global-intersection, global-merge, append-renamed). It stops short of explaining route structure such as path, occurrence, entry and exit, so the compensation is substantial but incomplete.

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 opening sentence gives a precise verb and resource: substitute one box's declared inner model into its parent through its checked input/output interface. It distinguishes itself from triz_nine_windows, which is explicitly described as a reader of the same inner model, and from flat analysis tools it says to call afterward.

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?

The description gives sequencing guidance ('expand nested boxes one at a time before requesting flat behavior, dynamics or resource verdicts') and names triz_nine_windows as the read-only alternative. It does not state explicit preconditions for when this tool should not be used, such as a box lacking an inner model, but the ordering and alternative are clear.

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