# Enrich an agent's answers

> Documentation index: [llms.min.txt](https://caseyrfsmith.github.io/scull/llms.min.txt) · Document manifest: [documents.json](https://caseyrfsmith.github.io/scull/documents.json)

Breadcrumbs: Build and use > 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:

```python
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:

```text
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:

```python
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`:

```bash
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:

```bash
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](https://caseyrfsmith.github.io/scull/docs/reference/query-layer.md) for discovery,
  then use context for the selected fields.
- Review the [schema format](https://caseyrfsmith.github.io/scull/docs/reference/schema-format.md) before authoring
  `applies_to` or `applies_when` metadata.