flow_pass

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

With no annotations, the description carries the safety profile. It discloses the materialization side effect ('one call materializes and caches the pass') and the global scope, and it details the return structure (taxonomy, taint-source flag, sink-flow signatures, pointer lifetime signatures). It does not explicitly state whether writes occur beyond the cache, leaving that inference to the agent, but the core behavioral traits are disclosed.

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?

Approximately 75 words across three sentences with zero filler. Each sentence delivers a distinct fact: the pass action and scope, the contents of the census, and the pipeline placement plus the scoping/pagination hints. Everything is front-loaded, beginning with the verb and the object most relevant to an agent deciding whether to call.

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?

Despite the missing output schema and absent annotations, the description leaves little to guess about the return values it enumerates (taxonomy, taint source status, ordered sink-flow signatures, and pointer lifetime signatures). Combined with the caching, scope, and pagination guidance, the definition is enough for the agent to select and invoke the tool correctly without further digging, which is remarkable given the complexity of its output.

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 50% — limit and offset lack schema descriptions — so the description must compensate. It does add meaning beyond the schema: 'Use `function` to scope to one function; paginate with offset/limit' clarifies the precise purpose of the undocumented offset/limit pair and reiterates `function` as the scoping key. The format parameter is already covered by its schema enum, which this description wisely does not repeat.

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 first sentence states a precise verb, resource, and result: 'Run the interprocedural flow pass (the 3rd pass) over the whole graph and return its per-function SUMMARY census.' It also distinguishes itself from sibling tools by positioning this as 'the layer beneath the skeletons' and 'the composed, interprocedural summary the shape matcher runs on,' separating it from flow, flow_skeleton, skeleton, and taint without opening their schemas.

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 by naming the pass, its ordering, the graph-wide scope, and the pipeline hole it fills. It also explains how to scope and paginate invocation. However, it never explicitly says when to prefer alternatives, such as flow, reaches, or taint, so the when-not-to-use guidance is left to be inferred from the pass composition rather than stated.

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