Script Tools#

Script tools are explicit ScriptToolConfig entries passed to Toolbox or loaded from script_tools runtime config. Each tool points to a local .py or .sh script and uses a JSON stdin/stdout envelope contract.

Execution contract#

  • Runtime sends JSON input over stdin.

  • Script prints exactly one JSON object on stdout.

  • Runtime validates output into canonical ToolResult.

Envelope shape#

Scripts must print one JSON object with keys:

  • ok

  • result

  • artifacts

  • warnings

  • error (optional)

Programmatic helpers#

from design_research_agents import ScriptToolConfig, Toolbox

runtime = Toolbox(
    script_tools=(
        ScriptToolConfig(
            name="rubric_score",
            path="examples/tools/script_tools/rubric_score.py",
            description="Score text with a simple rubric.",
        ),
    )
)
names = [spec.name for spec in runtime.list_tools() if spec.metadata.source == "script"]
result = runtime.invoke(
    "script::rubric_score",
    {"text": "hello"},
    request_id="docs-script",
    dependencies={},
)
runtime.close()

Troubleshooting#

  • Script tool missing from Toolbox.list_tools(): verify script_tools config and script path.

  • Unknown script tool: verify script:: prefix and canonical tool name.

  • stdout must be JSON: log to stderr, emit one JSON object on stdout.

Examples#

  • examples/tools/script_tools/README.md

  • examples/tools/script_tools/rubric_score.py

  • examples/tools/script_tools/repo_quickscan.sh