tools

Falcon Tools (pkg/core/tools)

This directory contains Falcon's tool set — modular, LLM-callable functions organized by domain and testing type. Tools are registered centrally via registry.go and exposed to the agent through the core.Tool interface.

Architecture Overview

Three layers:

1. The Registry (registry.go) — instantiates all tools with their dependencies and registers them with the agent.
2. Shared Libraries (shared/) — HTTP client, auth, assertions, variable substitution, and .falcon artifact management used by most tools.
3. Domain Modules — standalone packages (security_scanner/, performance_engine/, etc.) that encapsulate specialized testing logic.

Interaction Flow

Agent Core → Registry → Tool
                         ↓
                    Shared Libs
                         ↓
                   .falcon Artifacts
                         ↓
                     spec.yaml

All Tools by Domain

Core HTTP & Assertion Tools (shared/)

Persistence Tools (persistence/, shared/, agent/)

Debugging Tools (debugging/)

Testing Tools by Type

Smoke (smoke_runner/)

Functional (functional_test_generator/, agent/, data_driven_engine/)

Contract (idempotency_verifier/, regression_watchdog/)

Performance (performance_engine/)

Security (security_scanner/)

Integration (integration_orchestrator/)

Spec & Orchestration (spec_ingester/, agent/)

Module Organization

pkg/core/tools/
├── registry.go                    # Central registration of all tools
├── shared/                        # Foundation: HTTP, auth, assertions, artifacts
├── persistence/                   # Request, environment, variable storage
├── agent/                         # Memory, run_tests, auto_tester, session mgmt
├── debugging/                     # File I/O, code search, analysis, fix proposals
├── spec_ingester/                 # OpenAPI/Postman → spec.yaml + manifest.json
├── functional_test_generator/     # LLM-driven test scenario generation
├── data_driven_engine/            # CSV/JSON parameterized test execution
├── smoke_runner/                  # Minimal health check suite
├── idempotency_verifier/          # PUT/POST idempotency verification
├── regression_watchdog/           # Baseline snapshot comparisons
├── security_scanner/              # OWASP auditing + fuzzing
├── performance_engine/            # Load/stress/soak testing
└── integration_orchestrator/      # Multi-endpoint workflow execution

.falcon Folder Structure (Flat)

All artifacts use a flat structure — no subdirectories in reports/ or flows/. Filenames carry context via type prefix.

.falcon/
├── config.yaml
├── manifest.json
├── falcon.md                  # API knowledge base
├── spec.yaml                  # Ingested API spec
├── variables.json
├── sessions/
│   └── session_<timestamp>.json
├── environments/
│   ├── dev.yaml
│   └── prod.yaml
├── requests/
│   ├── get-users.yaml
│   └── create-user.yaml
├── baselines/
│   └── baseline_users_api.json
├── flows/
│   ├── unit_get_users.yaml
│   ├── integration_login_create_delete.yaml
│   └── security_auth_bypass.yaml
└── reports/
    ├── performance_report_users_api_20260227.md
    └── security_report_auth_api_20260227.md

Naming conventions:

• Reports: <type>_report_<api-name>_<timestamp>.md
• Flows: <type>_<description>.yaml

Tool Safety & Validation

Report Validation

After writing any report, ValidateReportContent() checks:

1. File exists and is > 64 bytes
2. Contains at least one Markdown heading (# or ## )
3. Contains at least one result indicator (table |, code block ```, or status keyword like PASS, FAIL, ✓, ✗)
4. Does not contain unresolved placeholders ({{, TODO, [placeholder])

falcon.md Validation

After memory(action=update_knowledge) writes to falcon.md, ValidateFalconMD() checks:

1. File exists and is > 200 bytes
2. Contains required sections: # Base URLs, # Known Endpoints
3. Each section has at least one non-blank line of content

falcon_write Safety

The falcon_write tool enforces:

1. Blocks ../ (no directory traversal)
2. Blocks absolute paths
3. Blocks writes to protected files (config.yaml, manifest.json, memory.json)
4. Validates YAML/JSON syntax before writing

write_file Confirmation

The write_file tool (source code writes) routes through ConfirmationManager — it emits a confirmation_required event with a unified diff before writing anything. The user must press Y to approve or N to reject.

Extending Falcon

Adding a New Tool

1. Create a module: pkg/core/tools/<new_module>/tool.go
2. Implement the interface:

type MyTool struct{}

func NewMyTool() *MyTool { return &MyTool{} }

func (t *MyTool) Name() string        { return "my_tool" }
func (t *MyTool) Description() string { return "Does something useful" }
func (t *MyTool) Parameters() string {
    return `{
        "type": "object",
        "properties": {
            "input": {"type": "string", "description": "..."}
        },
        "required": ["input"]
    }`
}

func (t *MyTool) Execute(args string) (string, error) {
    var params struct {
        Input string `json:"input"`
    }
    if err := json.Unmarshal([]byte(args), &params); err != nil {
        return "", fmt.Errorf("invalid args: %w", err)
    }
    // implementation
    return result, nil
}

1. Register in registry.go: add to the relevant register*() method
2. Validate reports: if your tool writes reports, call ValidateReportContent() after writing
3. Update the system prompt: if the tool adds a new capability, add it to pkg/core/prompt/tools.go

Quick Reference: Which Tool for Which Task?

For More Details

• Core Agent Logic: See pkg/core/README.md
• LLM Providers: See pkg/llm/README.md
• System Prompt: pkg/core/prompt/workflow.go and tools.go