Shared parameter semantics
params.md is a reference for parameters used to control execution in AI systems. Parameters define how work is executed (time, cost, retries, permissions, observability) — not what is being executed.
Why separate params from other concepts?
- The same parameters appear across many places. Defining semantics once prevents drift and ambiguity.
- Component docs can list supported parameters, while params.md owns the shared meaning (units, defaults, behavior).
- Parameters evolve faster than core abstractions; this keeps other docs stable.
Parameter index
A compact list of commonly used keys (illustrative, not exhaustive).
Execution
timeout_ms, max_cost_usd
Bound runtime, cost, and model usage.
Reliability
retries, retry_policy
Retry semantics and backoff behavior.
Safety
tool_allowlist, allowed_domains
Least privilege + scope limits.
Observability
trace, log_level
Debuggability and audit trail.
Conventions
units, defaults, inheritance
How params should be named and applied.
Usage
configs, overrides
Examples across documents.
Execution limits
Limits prevent runaway execution and create predictable operational behavior. These parameters are commonly enforced by execution runtimes and workers.
Maximum wall-clock time allowed for a single execution. When exceeded, execution should terminate cleanly and return a timeout status.
Example
timeout_ms: 30000Maximum estimated cost allowed for execution. Implementations may enforce this preemptively (before the limit is exceeded) using conservative estimates.
Example
max_cost_usd: 0.25Upper bound for token usage for the model call(s) in a single execution. This may map to provider limits or internal budgets.
Example
max_tokens: 8000Reliability & retries
Retries are a policy decision expressed as parameters. The goal is predictable behavior: what gets retried, how many times, and with what delays.
Number of additional attempts after failure. Implementations should define which errors are retryable (network, rate limit, transient tool failures) and which are not.
Example
retries: 2Strategy used when retrying. Recommended values:
- immediate — retry right away
- fixed_delay — wait a constant delay
- exponential — exponential backoff
Example
retry_policy: exponentialBase delay between retries. For exponential backoff, this is the starting delay. For fixed delay, this is the constant delay.
Example
retry_delay_ms: 500Safety & permissions
Safety parameters express least-privilege execution. These controls are often enforced by the runtime (before tools are invoked) and audited after execution.
List of tools that execution may invoke. Tools not listed should be rejected by default.
Example
tool_allowlist: [web_search, summarize, database_read]Network scope limit for web access. This is useful when tools include web browsing or HTTP calls.
Example
allowed_domains: ["docs.example.com", "api.example.com"]If true, forbid mutating actions (writes, deletes, sending emails) unless explicitly allowed by policy.
Example
read_only: trueObservability
Observability parameters control what execution emits: logs, traces, metrics, and artifacts. These should balance debuggability with privacy and cost.
Emit structured traces for tool calls and intermediate steps. Useful in debugging and audits.
Example
trace: trueControls verbosity of logs. Recommended values: error, warn, info, debug.
Example
log_level: "info"Emit execution counters and timings. This should be safe-by-default and not contain sensitive data.
Example
emit_metrics: trueNaming conventions
These conventions are intentionally simple. They exist to reduce ambiguity when parameters travel across systems and teams.
Be unit-aware
If a number has a unit, encode it in the name.
✓ timeout_ms, max_cost_usd, retry_delay_ms
✗ timeout, budget, delay
Prefer stable semantics
Avoid fuzzy keys that hide behavior.
✓ retries + retry_policy
✗ smart_retry
Defaults should be conservative
Prefer safe defaults (e.g., read-only, low budgets). Raise limits explicitly.
Inheritance should be explicit
Pipelines and agents may set defaults; per-step overrides should be clear and local.
Examples
Illustrative snippets showing how parameters can appear in other documents while keeping shared meaning here.
Example A — Worker configuration
A worker uses shared parameters to bound execution and limit tools.
# worker.md (conceptual)
worker: research
params:
timeout_ms: 30000
max_cost_usd: 0.25
max_tokens: 8000
retries: 1
retry_policy: exponential
tool_allowlist: [web_search, summarize]
trace: true
read_only: trueExample B — Agent chooses limits per task
An agent may select tighter or looser parameters depending on task risk and value.
# agents.md (conceptual)
route:
- when: task.type == "quick_answer"
use_worker: qa
with_params:
timeout_ms: 7000
max_cost_usd: 0.05
trace: false
- when: task.type == "deep_research"
use_worker: research
with_params:
timeout_ms: 60000
max_cost_usd: 0.80
retries: 2
retry_policy: exponential
trace: trueExample C — Pipeline defaults + overrides
Pipelines can set defaults once, then override per-step.
# pipelines.md (conceptual)
pipeline: weekly_digest
defaults:
params:
max_cost_usd: 1.00
timeout_ms: 60000
read_only: true
trace: false
steps:
- worker: research
params:
max_tokens: 12000
- worker: summarize
params:
timeout_ms: 20000Relationships
params.md is designed to be referenced by other concept documents without tightly coupling layout or ownership.
- worker.md lists supported params; params.md defines shared meaning.
- agents.md chooses params per task (within policy constraints).
- schema.md can validate types without changing human-readable docs.
- skills.md or similar catalogs may declare what tools/capabilities exist.
- claude.md (or model notes) may map vendor-specific fields to canonical params.
Status
Draft v0.1. Concept-first. Intended to establish shared vocabulary for execution parameters. Not a rigid standard and not tied to any specific vendor.
Future work may include a machine-readable schema, parameter mappings across runtimes, and clearer inheritance rules.