add_flow

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

With no annotations, the description must disclose side effects and constraints. It mentions that it adds flows and returns confirmation with flow ID(s), but does not describe validation rules, prerequisites (e.g., whether referenced assets/trust zones must exist), idempotency, or error behavior. This lack of context is a significant gap for a mutation tool.

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 description is structured with sections (Args, Returns) and is mostly efficient. However, the first line 'Add a new asset flow to the system' is repeated nearly verbatim in the second paragraph ('This tool adds one or more asset flows to the system'), which is redundant and could be tightened.

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?

Given the tool's complexity (13 parameters, no annotations, 0% schema coverage), the description covers the primary purpose and parameter semantics, but lacks critical contextual details. It does not specify validation behavior, dependencies on other entities (assets, trust zones), or the exact shape of batch items. The presence of an output schema partially mitigates the missing return-value details, but overall completeness remains moderate.

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?

The schema description coverage is 0%, so the description must compensate. It provides a parameter list with meaningful descriptions (e.g., 'ID of the asset being transferred', 'Risk level of the flow (1-5)') and clarifies that asset_id, source_id, and destination_id are required for single-item mode. However, it does not detail the structure of items for batch mode, which is a notable omission.

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 clearly states the action ('Add a new asset flow to the system') with a specific verb and resource. It distinguishes itself from sibling tools by focusing on asset flows and mentions batch operations via the 'items' parameter, which adds clarity.

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 explains how to use single vs. batch modes ('provide asset_id, source_id, destination_id, and optional fields directly' vs. 'provide a list of flow dicts in the items parameter'), which is useful. However, it does not explicitly state when to use this tool over alternatives (e.g., update_flow) or provide any when-not-to-use guidance.

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