Practical patterns for common AI agent tool scenarios.

Examples & Cookbook

Real-world patterns for building, validating, and composing AI agent tools with effector.

Example 1: Basic Validation

The simplest use case — validate an existing manifest:

# effector.toml
[effector]
name = "code-review"
version = "1.0.0"
description = "Reviews code changes and produces a structured report"

[effector.interface]
input = "CodeSnippet"
output = "ReviewReport"
context = ["Repository", "CodingStandards"]

[effector.permissions]
fs_read = true
network = false
npx @effectorhq/core validate .
✓ Schema valid
✓ Types resolved: CodeSnippet (input), ReviewReport (output)
✓ Context types: Repository, CodingStandards
✓ Permissions: fs_read only

Example 2: Compile to MCP

Take a typed manifest and produce a valid MCP tool definition:

npx @effectorhq/core compile . -t mcp

Output (mcp-output.json):

{
  "name": "code-review",
  "description": "Reviews code changes and produces a structured report",
  "inputSchema": {
    "type": "object",
    "properties": {
      "code": { "type": "string", "description": "Source code to review" },
      "language": { "type": "string" },
      "path": { "type": "string" }
    },
    "required": ["code"]
  }
}

The compiler maps CodeSnippet fields to JSON Schema properties automatically.

Example 3: Type Checking

Verify that your manifest uses valid types and the interface is consistent:

npx @effectorhq/core check-types .
✓ input "CodeSnippet" — valid (category: code, frequency: 0.72)
✓ output "ReviewReport" — valid (category: analysis, frequency: 0.45)
✓ context "Repository" — valid (category: reference, frequency: 0.68)
✓ context "CodingStandards" — valid (category: config, frequency: 0.31)
✓ All types resolved. 0 errors.

What happens with an invalid type:

npx @effectorhq/core check-types .
✗ input "CodeReview" — unknown type
  Did you mean: CodeSnippet, CodeDiff?
  Run `npx @effectorhq/core types` to see all 40 standard types.

Example 4: Custom Compile Target

Compile to a runtime other than MCP — for example, CrewAI:

npx @effectorhq/core compile . -t crewai

Output (crewai-output.py):

from crewai import Tool

code_review = Tool(
    name="code-review",
    description="Reviews code changes and produces a structured report",
    func=code_review_handler,
)

Supported targets: mcp, openai, langchain, crewai, json.

Example 5: Scaffold a New Project

Start from zero with the interactive scaffolder:

npx create-effector my-security-scanner
? Tool name: security-scanner
? Description: Scans repositories for security vulnerabilities
? Input type: Repository
? Output type: SecurityReport
? Permissions:
  ✓ fs_read
  ✓ network
  ✗ fs_write
  ✗ env_access

This generates:

my-security-scanner/
├── effector.toml        # Typed manifest
├── SKILL.md             # Human-readable capability doc
├── src/
│   └── index.js         # Handler stub
├── tests/
│   └── index.test.js    # Test scaffold
└── package.json

Example 6: Reverse Compile from MCP

Already have an MCP server? Generate effector.toml from it:

npx @effectorhq/core init --from-mcp ./my-mcp-server

The reverse compiler scans your source for server.tool() calls, infers types from the inputSchema, and generates a complete manifest with comments:

# Auto-generated by effector init --from-mcp
# Review and adjust types as needed

[effector]
name = "my-mcp-server"
version = "1.0.0"

[effector.interface]
input = "String"          # TODO: consider a more specific type
output = "JSON"

Example 7: Audit Permissions

Verify that declared permissions match actual source code behavior:

npx @effectorhq/audit check .
✓ fs_read: declared ✓, used ✓ (readFile at src/index.js:14)
✓ network: declared ✓, used ✓ (fetch at src/index.js:28)
⚠ env_access: reads GITHUB_TOKEN but not declared in manifest
  → Add to [effector.permissions]: env_access = ["GITHUB_TOKEN"]

Example 8: Compose and Verify a Pipeline

Check that a multi-tool pipeline is type-safe:

npx @effectorhq/core compose check ./git-fetch ./code-review ./slack-notify
Pipeline: git-fetch → code-review → slack-notify

Step 1: git-fetch
  output: CodeSnippet ✓

Step 2: code-review
  input:  CodeSnippet ← git-fetch.output ✓ (exact match, score: 1.0)
  output: ReviewReport ✓

Step 3: slack-notify
  input:  ReviewReport ← code-review.output ✓ (exact match, score: 1.0)
  output: SlackMessage ✓

✓ Pipeline valid. Total score: 1.0
  Aggregate permissions: fs_read, network
  Aggregate context: Repository, CodingStandards, SlackCredentials

Example 9: Quality Scoring

Evaluate how well-structured your tool definition is:

npx @effectorhq/skill-eval score .
Quality Score: 87/100

  Manifest completeness    ████████░░  8/10
  Interface completeness   ██████████  10/10
  Type specificity          █████████░  9/10
  Permission granularity   ████████░░  8/10
  SKILL.md quality         ████████░░  8/10
  Example quality          ██████░░░░  6/10  ← Add more examples
  Description clarity      █████████░  9/10
  Composability            ██████████  10/10
  Naming conventions       █████████░  9/10
  Documentation coverage   ██████████  10/10

Example 10: Using the Fluent API

For programmatic use, the fluent API chains operations:

import { Effector } from '@effectorhq/core';

const result = await Effector
  .fromDir('./my-tool')
  .validate()
  .checkTypes()
  .compile('mcp');

if (result.errors.length > 0) {
  console.error('Validation failed:', result.errors);
} else {
  console.log('MCP output:', result.output);
}

Next Steps