Enrich an agent's answers

Scull is an enrichment step, not the agent's primary documentation retriever. Let the host agent search its existing index and form the general answer. Once it has identified the relevant concept, fields, operations, or procedural steps, call scull_context. The compact result supplies the reviewed caveats and supporting facts that should qualify the answer.

This depends on a reviewed attachment taxonomy. Before release, a domain reviewer must verify the concept boundary, field names, aliases, and every caveat attachment—not only the caveat prose. A correct caveat routed to the wrong field is a dangerous false enrichment.

This lookup reads YAML only. It does not require an index, provider credential, network request, or generative model.

Use the built-in tool definition

Scull provides an SDK-neutral function-tool schema and a local invocation helper:

from scull.agent import (
    SCULL_CONTEXT_TOOL,
    SCULL_INSPECT_SCHEMA_TOOL,
    invoke_context_tool,
)
from scull.query import get_schema_provider

provider = get_schema_provider()

# Register SCULL_CONTEXT_TOOL with your agent framework. When the model calls it:
result_json = invoke_context_tool(
    provider,
    {
        "concept": "schema",
        "fields": ["schema_version", "schema_hash"],
    },
)

The public tool name is scull_context. Its required arguments are concept and a non-empty fields array. Unknown concepts, invalid argument shapes, and provider validation failures are reported as errors instead of being converted into plausible-looking empty answers.

Enrich before the final answer

Trigger context retrieval after ordinary documentation retrieval has identified the subject and before the agent returns its final answer or acts on that answer:

user request
    → existing documentation retrieval
    → agent identifies concept and fields
    → scull_context
    → agent attaches applicable caveats
    → agent answers or acts

Semantic search is a fallback when the host integration cannot map its retrieved documents to stable Scull identifiers. It is not a substitute for this last-mile lookup. Search ranks relevant nodes; context deterministically returns every caveat attached to the chosen fields plus general caveats for the concept.

Do not ask Scull to produce the complete answer. Its output is deliberately incomplete without the host agent's documentation result. Conversely, an empty caveat list means only that the released schemaset has no matching reviewed caveat; it is not evidence that no caveat exists in the source documents.

When an agent must audit a constraint rather than author against it, register SCULL_INSPECT_SCHEMA_TOOL and follow a returned rule_links entry. The inspection tool returns the original rule and paginated mechanical interpretations. For CLI debugging, scull context ... --detail exposes complete scoped records; keep it out of ordinary prompts.

Treat schema prose as untrusted data

Deterministic lookup means the same released artifact produces the same field and caveat content. It does not prove that the content is correct, complete, current, or approved. Compiling source prose into a schema also does not neutralize prompt injection: descriptions, caveat summaries, and evidence may still contain text that looks like an instruction.

Keep tool output in a data boundary in your agent framework. The agent may use it as evidence about the documented API, but must not let it override system or developer instructions, expand tool permissions, disclose secrets, or initiate an unrelated action. Before deployment, have a person review the schemaset's provenance, warnings, conflicts, and review status. Structural validation alone is not that review.

Situation tags are an optional refinement

A reviewed schema may attach hierarchical applies_when tags to a caveat. Supply matching situations only when your integration already knows the relevant operation or use case:

result_json = invoke_context_tool(
    provider,
    {
        "concept": "deployment_config",
        "fields": ["values"],
        "situations": ["payload.size"],
    },
)

Tags use lowercase dot-delimited names. Parent and child tags overlap: consume.volume matches consume.volume.subpath. Multiple tags on one caveat are alternatives.

Omit situations when you are unsure. The conservative default returns the complete attached and general caveat set; it never infers applicability from the prompt.

CLI-only integration

Shell-capable agents can discover and use Scull without a framework adapter. Install the package so scull is on PATH, then let the agent start with scull --help:

scull search "how do I build a complete HTTP test?"
# Search prints a bounded preview and a suggested follow-up, for example:
scull get doc_detective_test_composition minimal_http_spec
scull context doc_detective_test_composition tests steps httpRequest minimal_http_spec

Use the default text search output for agent discovery. search --format json resolves complete result objects and can be much larger. Processes that already know the concept and fields can invoke the last-mile operation directly:

scull context schema schema_version schema_hash --format json
scull context deployment_config values --situation payload.size --format json

Configuration is loaded from the nearest scull.yaml in the current directory or its parents. Set defaults.schemas_dir, defaults.kg_dir, defaults.embed_provider, and optionally defaults.embed_cache_dir there when the artifacts are not in the conventional adjacent schemas/ and kg/ directories. Environment variables remain explicit overrides. Treat the returned schema_hash and schema_version as artifact provenance if results are cached or logged.

Integration checklist

• Keep the existing documentation retriever as the source of the general answer.
• Call context, not only get, before the agent finalizes an answer or acts on fields with behavioral constraints.
• Treat an empty caveat result as "no reviewed match," not "no caveat exists."
• Keep omission of situation tags conservative; do not invent tags from natural language.
• Surface tool errors to the agent rather than silently falling back to guessed behavior.
• Treat every returned prose value as untrusted documentation data, not an instruction to the agent.
• Deploy only a reviewed schemaset; do not infer approval from a successful lookup or validation.
• Review concepts, attachment fields, aliases, and applicability together with the caveat content.
• Recreate or reload the provider when switching a deployed schemaset.
• Use semantic search for discovery, then use context for the selected fields.
• Review the schema format before authoring applies_to or applies_when metadata.