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

With no annotations, the description must carry behavioral disclosure and it does a lot: Placeholder Data values are truncated, issues include per-service missing required config, suggestions never affect running the flow, and the configId mode is a read-only snapshot rather than an exact reconstruction. It never explicitly states the default call is read-only/no side effects, nor does it mention response size or any cost/limit beyond the word 'compact'.

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?

Front-loaded with the return contents, which is the right order, and most clauses carry real information. But the payload list is a single very long run-on sentence, and the configId paragraph packs four separate facts into one dense block, so it is harder to parse than its length justifies.

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?

There is no output schema or annotation, so the description is the only disclosure of return values — which it covers thoroughly, including truncation and the configId variant. The gaps are on the input side (workspaceId, versionId sourcing) and on scale (how large a 'compact' overview gets), which matter for a 3-parameter tool with zero schema coverage.

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 0%, so the description must define all three parameters. It explains configId well (source tool, paired with that run's versionId, and how the behavior changes under it) and implicitly ties versionId to that pairing, but workspaceId is never mentioned and versionId's own meaning outside configId mode is left undefined.

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 concrete resource ('compact overview of the flow') and enumerates exactly what it returns: node id/type/name/status, edges, description, Initial Data fields with descriptions and consumers, Placeholder Data, flow-wide issues, and suggestions. That is far more specific than the bare name. It stops short of naming the sibling it replaces (get_flow_json, get_node_details), so an agent still has to infer the boundary from those tools' own descriptions.

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?

It gives a clear timing rule ('Call before wiring or finishing, not after every add_block') plus a mode switch: use configId from get_flow_instance together with that run's versionId to read the flow as it was at run start. That is explicit when-to-use and a stated negative case. It does not name a competing tool (e.g. get_flow_json) or explain when to prefer it over get_flow_instance.

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