ObneyAI/orc / orc-skills/orc-tools
orc-tools
VerifiedBuild and use ORC tools through authored tool leaves, guarded code callers, described catalogs, typed dynamic or finite arguments, recursive specialist chains and parallel actions. Use when selecting, invoking, composing or debugging tools, including researcher-generated tool nodes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.2 KB |
| agents/openai.yaml | config | 249 B |
| references/bounded-workspace-acceptance.md | markdown | 4.0 KB |
| references/catalogs-and-arguments.md | markdown | 10.1 KB |
| references/current-invocation.md | markdown | 6.3 KB |
| references/current-proofs-and-limits.md | markdown | 9.6 KB |
| references/researcher-tools.md | markdown | 14.1 KB |
| references/tools-as-behaviors.md | markdown | 8.8 KB |
references/catalogs-and-arguments.md
View on GitHub# Described catalogs and argument contracts
## What the model must see
A catalog entry should answer: what goal can this capability establish, when is it applicable, what information must be supplied, what does each argument mean, what does its result prove, and what are its limits? Include a stable ID and relevant effects. For a specialist, describe its child-tree goal and input/output contract; its internal node list usually adds no selection value. Distinguish overlapping capabilities by evidence requirements and outcomes, rather than names alone.
An example catalog can offer `find-sources` (open query plus bounded result count), `read-source` (one source ID returned by discovery), and `save-note` (source ID and new note text, with an operation ID assigned separately by the host). Explain that discovery returns candidates, reading returns source evidence, and saving requires a retrieved source. This prevents the model treating search snippets or its own remembered text as a completed grounded note. A fourth `no-applicable-capability` outcome should carry a typed reason and route to the appropriate clarification/defer behavior.
Use structured, described schemas both for the catalog shown to the model and for enforcement by the host. Tool metadata only helps if it is included in the actual request. A hand-assembled router can read a typed catalog blackboard value containing descriptions and schema data; an LLM argument leaf should read the selected contract, goal and relevant observations. ORC serializes complex input values. The repaired function and structured-output paths include the input-field guide for supplied inputs; older function paths omitted these descriptions. Inspect the resolved source and actual request rather than assuming either behavior. Include capability purpose, argument meanings and result limits in the actual catalog value: generic field descriptions cannot supply a missing capability contract. See [model/SIO](../../orc-model-sio/SKILL.md) for mode and revision details. A researcher needs bound tool contracts plus separate semantic descriptions where its schema format has no description slot.
The [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) distinguishes tool descriptions, input schemas, output schemas, structured results and execution errors. MCP annotations are metadata, not authorization. An ORC leaf's structured output schema, a host tool's argument schema and a tool result's schema serve different boundaries; passing one does not validate the others.
## Finite decisions versus generated arguments
| Contract | Model responsibility | Host responsibility |
| --- | --- | --- |
| Finite route | Choose a described capability or abstain | Validate ID, confidence policy and eligibility |
| Finite argument | Choose from supplied IDs/enums/booleans | Check membership, cross-field compatibility and freshness |
| Open argument | Produce typed text/numbers/collections/maps | Validate selected schema, bounds and domain constraints |
| Effect proposal | Propose a meaningful action | Authorize, persist through commands, confirm outcome |
Jev [Choice](https://docs.typesafe.ai/primitives/choice) operates over supplied options. Option IDs and descriptions have meaning; a question ID is not a substitute for instructions. A model may select one discovered source ID but cannot invent a free-text query or note body through that finite head. Generate those values with a suitable LLM or compute them from trusted data. Native protocol integration and raw assessment/policy separation live in [decision contracts](../../orc-decision-models/references/contracts-and-observability.md).
An ordinary ORC `llm` leaf can write a described structured argument map through SIO. Define the actual fields with Malli, for example `[:map {:closed true :description "Arguments for the selected source discovery capability"} [:query [:string {:min 1 :description "Search expression derived from the user's information need"}]] [:limit [:int {:min 1 :max 8 :description "Maximum candidates requested"}]]]`. Use a specific schema per capability. After parsing, validate the joint proposal: a well-typed source ID may still belong to the wrong tenant or an earlier observation.
If selection and arguments are generated together, use a supported discriminated contract or validate a route-tagged proposal against the selected schema. If separate leaves are simpler, select first and prepare only that capability's arguments. A decision batch may ask hypothetical finite argument questions for several capabilities; consume only the selected capability's answers. Refresh evidence for arguments depending on earlier tool results. Copy opaque resource IDs verbatim; normalizing an argument field name is not permission to alter an ID value. Native declared contracts reject ambiguous field aliases before validating a decoded key view, including nested structures, while passing original arguments/results unchanged. Enforce aliases explicitly at custom uncontracted boundaries too.
Do not accept unrestricted model-produced function names, FQNs or delegate sheet IDs as authority to invoke arbitrary code. The host maps catalog IDs to allowed implementations. For known specialists, build guarded delegate branches using actual sheet IDs; for a host dispatcher, validate and select an allowlisted injected capability. A model selects intent; the application owns executable authority.
## Caller boundary
Use the native `:tool-contracts` guard for declared argument/result schemas on code, tool and researcher calls. Missing/`:untyped` sides remain permissive; contracts neither restrict tool-name selection nor enforce authority. Validate catalog membership and enforce permission, tenant, resource identity, limits and deadline at the host boundary. At the pinned Grain revision, direct command/query processors do not execute registry `:authorized?` predicates. Use an enforcing adapter or an explicit injected-capability/handler guard before effects and protected reads; trusted claims alone do not enforce authority. The [Grain example](../../orc-grain-application/references/contracts.md) supplies guarded handlers and complete UUID/offset-date-time envelopes. Validate returned data before exposing it as successful evidence. Distinguish invalid proposal, denied action, transport/provider error, tool execution error, empty valid result, and incomplete goal. An error map is ordinary data unless explicitly translated into an appropriate node/domain outcome. Result validation after invocation cannot undo an effect already performed.
Persist effects through authorized Grain commands with event schemas, then verify read models/queries. Inspect the command response for rejection before reading the projection: an old record under the same operation key must not hide a failed new proposal. Bind an operation identity to its accepted payload: same identity with the same payload may return the prior outcome; a changed payload must be rejected or explicitly versioned. For one-to-many actions, validate the full batch and prepare distinct host-issued operation identities in a separate code node before any effect. Persist each identity with its original argument payload in typed writes so replay/retry uses the same intent. Keep operation identity out of model-generated argument authority; reject duplicates and unrelated historical collisions before dispatch. Preserve each original argument payload with its host-issued operation identity. Match its returned receipt and authoritative projected record to that exact identity, resource, payload and trusted actor/tenant before completing the parent. Cardinality and membership alone can accept the same old receipt twice while none of the new actions occurred. Test a capability returning another action's receipt, a duplicate receipt, and a prior unrelated committed record. Result validation cannot roll back an already performed effect.
Sequential replay evidence alone does not prove concurrent exactly-once execution. External effects require their own idempotency/reconciliation strategy.
Capture the exact outgoing model body, selected schema version, parsed proposal, accepted caller arguments and relevant result without credentials. For errors retain only allowlisted class/kind and bounded status values. Exception messages, causes and ex-data may contain credentials or request content. Do not call a synthetic native client a live decision-model experiment.
Sanitize at the injected tool/provider boundary before a failure reaches ORC, not only in a diagnostic log. Cover synchronous throws, asynchronous error callbacks, failed returned futures/completion stages and returned error results wherever the client supports them. Propagate fixed safe failure text and vetted class/status data; drop original messages, cause chains, ex-data and raw throwables. Do not attach the original exception as a cause, return its failed future after sanitizing only the callback, or forward an unfiltered error result. Preserve failure meaning: a sanitized map remains code-node data until the caller explicitly translates it into an appropriate failure. Verify [canonical persisted failures](../../orc-observe-debug/references/evidence-path.md#verify-safe-persisted-failures); safe logger output does not prove safe completion events.
For retrieval, validate that the returned source identity equals the exact identity requested from the discovery observation, on every attempt and retry, before passing it to generation or persistence. A well-formed result with a different ID is a failed selected retrieval. Comparing a generated note to that wrong result does not establish the requested provenance. For intentional identity remapping, require a described, validated mapping from the original observation.
A described `none`, unavailable or no-match option is part of the callable behavior's contract. Route that valid result to an explicit unresolved outcome or another eligible method. A selector offering `none` followed by code that throws on every non-tool choice leaves an ordinary semantic outcome unhandled. Keep missing authority, a rejected argument contract and a tool execution exception distinct in the evidence and recovery policy.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |