Skip to content

[Gap]: Document default step outputs for composite tools #489

@jerm-dro

Description

@jerm-dro

What needs documentation?

Composite tools now support configuring default return values for steps that may be skipped. This is important when:

  • A step has failureMode: "continue" and an error occurs
  • A step has a condition that evaluates to false

Without defaults, downstream steps that reference the skipped step's output would receive empty strings, causing unexpected behavior.

Key features that need documentation:

  • The defaultResults field in composite tool step configuration
  • When and why to use defaultResults
  • Validation behavior: an error is produced if a step may be skipped, its outputs are referenced downstream, and no defaults are configured
  • Examples showing usage with conditional steps and failureMode=continue

Context and references

Implementation issue: stacklok/toolhive#2989

Use case

As a platform engineer configuring composite tools, I want to be able to configure default step outputs in the event a step is skipped (e.g. conditional, ignored error), so that my composite tools continue to behave as expected under all possible branches.

Additional context

Example configuration:

step:
  ...
  defaultResults:
    "some_returned_value_name": "default value for downstream"

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions