gx3_data_flow

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

With no annotations, the description carries the full behavioral burden and meets it well. It explicitly discloses that unknown or partially parsed operations yield unresolved records, that no guessed edge is emitted, that results are conservative, and that device comments appear only when available. This is specific, honest behavior disclosure beyond what the schema provides.

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?

Three tight sentences deliver the core purpose first, then the shape of successful results, and finally the unresolved-fallback behavior. There is no filler, no repetition of schema details, and every sentence earns its place.

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 with no output schema, the description does a good job explaining what an agent should expect: edge fields, unresolved records, no guesses, and conditional device comments. The main gap is that it doesn't describe the effect of the 'format' parameter or the overall result envelope, though the schema partially covers format via its enum.

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 already documents root, device, and opcode, and format is self-explanatory via its enum and default, so a baseline of 3 is appropriate. The description adds no parameter-level semantics: it does not clarify how 'device' filtering affects edges, how 'opcode' restricts results, or how 'format' changes output. It neither harms nor significantly enhances what the schema already conveys.

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 states a specific verb and resource: 'Build conservative argument-level source-to-destination value-flow edges.' It is distinct from sibling tools like gx3_xref_where_used or gx3_list_commands by specifying the exact object produced, and the edge-detail clauses remove any ambiguity about what the tool returns.

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 clear context for when the tool would be relevant: anywhere value-flow edges are needed, with a conservative no-guessing policy. However, it never names alternative tools or states when not to use this tool, so an agent must infer selection among the many gx3 siblings rather than being explicitly routed.

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