triz_bond_graph

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

No annotations exist, so the description carries the full burden. It does disclose meaningful traits: the analysis runs by 'bounded propagation and search' (explaining the max_steps bound) and explicitly excludes numeric simulation. It does not say whether the model is read-only or mutated, whether results are deterministic, or what happens when no ordering can be established.

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?

A single dense sentence with the verb and scope front-loaded, and zero filler. It is compressed to the point of opacity in places ('derivative causality'), but no sentence is wasted.

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 tool taking a very large nested model with no output schema and no annotations, the description is only modestly complete. It covers what is computed and the simulation boundary, but not the shape of the returned report, error conditions on malformed energy declarations, or how the analysis depends on the declared bond elements.

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 reported at 0% for the two top-level parameters, and the description does not explain max_steps at all. However, 'on declared energy subsystems' adds a real constraint beyond the schema (the Carrier.energy block is optional in the schema), telling the agent what the model must contain for this check to be meaningful.

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 description names a specific operation ('Assign effort/flow causality on declared energy subsystems') plus its outputs ('report derivative causality and direct algebraic dependency cycles, and export constitutive equation structure'). It distinguishes itself from function-rating siblings by scoping to energy subsystems and causality, though the jargon ('derivative causality', 'constitutive equation') assumes domain fluency.

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?

Usage is only implied: the tool applies to models whose carriers are explicitly energy subsystems with effort/flow pairs. The clause 'No numeric simulation' gives a useful when-not boundary, but no prerequisites (e.g. energy carriers must be declared) and no routing to or from siblings like triz_graph, triz_behavior, or triz_feasibility are stated.

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