Resource query syntax

Toolang 0.4.0 uses native TQ queries for models, tools, and caps. Queries match the same records exposed by --json. Use too, the recommended command alias.

Collections and identity keys

Providers support --json inspection, but no built-in --query option. Plugin inventories and runnable lists also have no collection-query interface. There is no standalone too query command.

Default lists show effective resources. -a/--all also includes unavailable or excluded resources in the selected scope; queries then filter that view. Use --json for complete records or --human for tables. These output options are mutually exclusive.

Effective cap view

Caps with the same kind and name resolve in here > home > root order: current-module inline/referenced definitions, agent-home definitions, then root-shared definitions. Only the winning definition reaches the query view. --all includes allow-excluded winners in that scope; it does not restore shadowed definitions or expose another agent's home. Conflicting definitions within one scope are errors, rather than another precedence layer.

Patterns and predicates

A selection has an identity pattern, optionally followed by predicates:

PATTERN[PREDICATE;PREDICATE],OTHER_PATTERN

Patterns match the complete identity key. Use * for any sequence of characters and ? for one character. For example, openai/*, fs/*, or skill/* selects a namespace. A bare reviewer does not search cap names across kinds; use */reviewer for that selection.

Semicolons combine predicates. A comma or repeated -q/--query option forms a union. Shell-quote queries so brackets and wildcards reach too unchanged.

too models -q 'openai/*[tool_call;limit.context>=200000]' --json
too models -q 'openai/*' -q 'anthropic/*'
too tools -q 'fs/*' --json
too alice caps -q 'skill/*[tags has all (home,remote)]' --json

Predicates use native TQ operators, including equality and numeric comparisons. Nested fields use dotted paths. Arrays use has, has no, and has all (...):

too models -q '*[context>=200000]' --human
too models -q '*[modalities.input has image]' --json
too tools -q '*[parameters has path]' --json
too caps -q 'skill/*[tags has no not_allowed]' --json

Select the identity directly: skill/reviewer, not *[cap="skill/reviewer"]. TQ validation rejects predicates on the identity key. Other fields have no Toolang-specific allowlist; absent fields generally produce no matches. Values and operator/type compatibility follow TQ semantics.

For example, this projection contains two tools:

[
  {"ref": "fs/read", "parameters": ["path"], "tags": ["ready"]},
  {"ref": "shell/run", "parameters": ["command"], "tags": ["ready"]}
]

fs/*[parameters has path] selects only fs/read; *[tags has ready] selects both. The query chooses records from the selected inventory view.

Operators and literals

Unquoted numbers and true / false are typed literals. Double-quoted JSON strings represent text containing spaces or query punctuation, or text that would otherwise parse as a number or Boolean. For example:

too models -q '*[name="Example model"]' --json

image in input and image not in input are reversed spellings of input has image and input has no image.

Boolean shorthand tests equality, not general truthiness or field existence. A missing field never matches, including != and negative membership tests. null field values do not satisfy inequality or ordered comparisons. Collection membership checks array elements or object values; it does not search substrings or object keys. Patterns are case-sensitive; double-quote an identity to match it literally instead of treating * as a wildcard.

Record fields

Model inspection shortcuts such as context and input coexist with the underlying limit.context and modalities.input fields. price is a formatted per-million-token display string; use numeric cost.input and cost.output for numeric comparisons. Optional catalog fields may be absent; inspect the selected records with --json.

For caps, cap is the effective kind/name identity, source is the resolved Source Ref, and location is the human-facing content address. Only inline locations include a source line. A skill location points to its SKILL.md. See Source refs.

Tags

Tags form one flat array. Models expose their canonical _toolang.tags as the inspection shortcut tags; tools and caps expose tags directly.

ready excludes blockers; independent blockers can coexist. Tools and caps are ready when allowed. Provider records have no tags; use _toolang.ready_count and _toolang.model_count when inspecting provider JSON.

Ordering and resource policy

Model selections use first matching query branch, then source order within that branch. Tools and caps retain base order. Unions deduplicate overlapping matches. No matches produce an empty collection.

Querying an inventory does not change policy or select a model for execution. too models -q 'openai/*' filters inspection output; a run's --model option still requires an exact model identity. all and none are policy sentinels, not special inventory query expressions: use * to match all identities.

The same syntax is used by [allow], TOOLANG_ALLOW_<FIELD>, --allow, Chat :allow, one-run /allow, and runnable resource directives:

too alice serve --allow 'models=*[tool_call]' --allow 'tools=fs/*'

agic review:
  tools = fs/*
  Review the supplied material.

Allow settings accept standalone all or none sentinels, without mixing them with queries. Resource directives use * for all inherited resources or none for the empty set. Directive =, +=, and -= respectively intersect, include, and exclude within the inherited ceiling; they do not expand external authority.

For a runnable whose inherited tools are fs/read and fs/write:

External TQ

With the optional tq-json[cli] package installed, query JSON outside Toolang:

too models --json | tq -r -k ref '*[tags has all (ready,local)]'
too providers --all --json | tq -k id '*[_toolang.ready_count=0]'
too caps --json | tq -k cap 'skill/*'

The TQ CLI emits individual objects; -r preserves model query branch priority. Use the correct identity key. Toolang validates resource expressions before matching; external TQ consumers should apply equivalent key validation.