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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing that the sequence projection is 'computed from the graph', explaining the residualNodeIds semantics, and signaling not-found behavior rather than an exception.

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 dense sentences with zero waste: the first front-loads the core action and return shape, the second gives usage scenarios, and the third handles the error case. Every sentence earns its place and the most important information comes first.

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 having no output schema, the description compensates by enumerating the return contents (nodes with their fields, edges, lanes, knobs, memberNodeIds, residualNodeIds) and the not-found fallback. Safety is covered by annotations. Minor gaps remain, such as ID format and whether residualNodeIds is always present, but for a single-parameter read tool this is nearly complete.

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 compensate. It does clarify that workflowId identifies the workflow being fetched and directs the agent to campaignstack_list_workflows as a source of valid IDs. However, the parameter meaning is largely self-evident from its name and the first sentence, and no format, scope, or validity detail about the ID is added.

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 uses a specific verb+resource ('Get a workflow by ID') and enumerates exactly what is returned: nodes with fields (type, label, config, position, execution target), edges, and a computed sequence projection with lanes, knobs, and memberNodeIds. This rich detail clearly distinguishes it from siblings like campaignstack_get_workflow_stats and campaignstack_get_workflow_node_types.

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 states explicit use cases ('Use it to describe the workflow the way the user reads it and to find which node ids a step owns') and gives a named alternative with a triggering condition ('If the workflow is not found, use campaignstack_list_workflows to find valid workflow IDs'). The agent knows exactly when to call this tool and how to recover from failure.

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