fence-params

Fence Parameters API

Self-documenting fences with queryable parameter schemas.

Overview

Labeled fences can expose their parameters via a structured API, enabling tooling (neovim, IDEs, CLI) to provide parameter hints and validation.

API Endpoint: GET /api/oculus/fences/{fence_id}/params

The Self-Documenting Pattern

Write fences with inline documentation:

```python[my-tool]
"""
🔧 Tool Name

Brief description.

PARAMS:
  name (string): What it's for
  count (int): How many [optional, default: 10]
  verbose (bool): Enable verbose output [optional, default: false]

RETURNS:
  { result: ..., metadata: ... }
"""

name = config.get('name')
count = config.get('count', 10)
verbose = config.get('verbose', False)

result = {"processed": count, "name": name}
```

Parameter Sources

The params API extracts from two sources:

1. PARAMS: in Docstrings

PARAMS:
  param_name (type): Description
  optional_param (type): Description [optional, default: value]

Format: name (type): description [optional, default: X]

2. Config YAML Sections

### config

```yaml
name: "default value"
count: 10
verbose: false


When both exist, they're merged:
- Docstring provides: type, description, optional flag
- Config provides: default values

## API Response

```json
{
  "fence_id": "my-tool",
  "fence_label": "my-tool",
  "slug": "my-node",
  "params": [
    {
      "name": "name",
      "type": "string",
      "description": "What it's for",
      "default": "default value",
      "optional": false,
      "from": "merged"
    },
    {
      "name": "count", 
      "type": "int",
      "description": "How many",
      "default": 10,
      "optional": true,
      "from": "merged"
    }
  ],
  "required": ["name"],
  "optional": ["count", "verbose"],
  "example_call": {
    "fence_id": "my-tool",
    "params": {
      "name": "<string>",
      "count": 10,
      "verbose": false
    }
  }
}

Usage Examples

curl

curl "http://localhost:7778/api/oculus/fences/magic-8-ball/params"

Neovim Integration

See neovim-wanderland for picker integration that fetches params hints.

MCP Tool Discovery

// Get params before executing
const params = await fetch(`/api/oculus/fences/${fenceId}/params`).then(r => r.json());
console.log(`Required: ${params.required.join(', ')}`);
console.log(`Example: ${JSON.stringify(params.example_call.params)}`);

// Then execute with valid params
oculus_execute_fence({
  fence_id: fenceId,
  params: params.example_call.params
});

Best Practices

Always document PARAMS - even for simple tools
Use consistent type names - string, int, bool, array, object
Mark optional params explicitly - [optional, default: X]
Provide sensible defaults - in docstring or config section
Keep descriptions concise - one line per param

Slots

North

slots: []

South

slots: []

West

slots:
- context:
  - Fence params API extends the core fence system
  slug: cmd-fence
- context:
  - Linking fence params API docs to core fence docs
  slug: cmd-fence

East

slots:
- context:
  - Linking neovim guide to fence params docs
  slug: neovim-wanderland
- context:
  - Client API builds on fence params
  slug: oculus-client-api