--- name: factfile-intake description: Introspect this repository's AI agent and emit a standardized capability declaration — declared-profile.json plus a one-page action summary covering purpose, surfaces, tools, write authority, money-touching actions, data access, escalation, and version identifiers. Use when documenting what the agent can do, answering an enterprise buyer's diligence questions about its actions or authority limits, or preparing an Agent Factfile dry run. --- # Agent Factfile intake — declare what this agent can do Introspect this repository and produce a standardized declaration of the AI agent it contains. Write two files to the repository root: - `declared-profile.json` — structured and machine-readable. - `declared-actions.md` — one page a person reads in two minutes. This is a declaration. It records what this repository's code, configuration, and prompts say. It is not evidence. Nothing in it has been observed by anyone outside this repository. ## Rules 1. Report only what you find in code, configuration, or prompts. Cite a file path for every entry. 2. Mark anything you cannot confirm as uncertain and list it in `uncertain`. A stated gap is more useful than a confident guess. 3. Never invent a limit. If a ceiling, allowlist, or approval gate is not in the repository, it does not exist for this purpose. 4. If a limit appears only in a prompt and nothing in code enforces it, record it as `prompt_level_only`. A model can be talked out of a prompt. 5. Do not open, decrypt, or copy secrets. Record that a credential exists and what it reaches. Never record its value. 6. Do not run the agent. Read it. 7. If the repository holds more than one agent, ask which one, or emit one pair of files each. ## What to read System and developer prompts. Tool, function, and MCP schema definitions. The dispatch layer that maps a tool name to the code that runs, and the HTTP calls and SQL those tools make. Policy and guardrail modules. Routers, middleware, and webhook handlers — they tell you the surfaces. Deployment config and environment variables. Tests, which often state limits the code does not enforce. ## What to enumerate 1. **Purpose.** One paragraph: what this agent is for, who it serves, in what environment. Take it from the repository's own prompts and docs, not from a marketing page. 2. **Deployed surfaces.** Every channel the agent is reachable on: chat widget, email, API, voice, Slack, helpdesk platform. For each, name the platform and say whether the caller is authenticated. 3. **Tools.** Every tool, function, or MCP call the agent can invoke. Name, what it does, a one-line summary of its input schema, and the file it is defined in. Include tools that are registered but rarely used. 4. **Write authority.** Which of those tools mutate state — create, update, delete, send, charge. List them separately. A read-only agent and a writing agent are different products. 5. **Money-touching actions.** Refunds, cancellations, discounts, credits, subscription changes, anything that moves money or entitlement. For each: the limit, where the limit is enforced, and what approval gate exists. If there is no limit, say there is no limit. 6. **Data access.** What customer, order, and account data the agent can read. Then the specific question: can it read data belonging to a customer other than the one it is talking to? Check whether each query is scoped by a verified identity or by an identifier the user supplies. Answer `no`, `yes`, or `uncertain`, per surface if the answer differs. 7. **Escalation.** When the agent hands off to a human, how the handoff happens, and what it is instructed never to do. Say whether each is enforced in code or requested in a prompt. 8. **Version identifiers.** Whatever pins this exact agent: model id, prompt digests, toolset source and tool count, config digests, repository commit. Digest a file with `shasum -a 256 `. For a value that is not a file, such as a model id, hash the exact string with `printf '%s' "" | shasum -a 256`, and record the plain string too. ## declared-profile.json Emit exactly this shape, and keep the key names. A filled-in synthetic example is at https://agentfactfile.com/skills/example-declared-profile.json ```json { "schema_version": "declared-profile/0.1", "generated_at": "", "generated_by": "", "subject": { "vendor": "", "product": "", "version": "", "model_digest": "sha256:<64 hex>", "prompt_digest": "sha256:<64 hex>", "policy_digest": "sha256:<64 hex>", "toolset_digest": "sha256:<64 hex>" }, "declared_profile": { "purpose": "", "intended_users": [""], "intended_environment": "", "dependencies": [""], "autonomy": { "mode": "answer_only | recommend_only | bounded_action | open_action", "human_oversight": "", "financial_authority_usd": 0, "financial_authority_basis": "code_enforced | prompt_level_only | no_limit_found | not_applicable", "can_access": [""], "cannot_access": [""] }, "capability_claims": [ { "id": "", "workflow": "", "claim": "", "user_outcome": "", "success_definition": "", "consequence_if_wrong": "low | moderate | high | critical" } ], "surfaces": [ {"channel": "", "platform": "", "caller_authenticated": "yes | no | uncertain", "source": "path:line"} ], "tools": [ { "name": "", "does": "", "inputs": "", "mutates": true, "touches_money": false, "limits": [{"limit": "", "enforced_in": "code | prompt_level_only | uncertain", "source": "path:line"}], "source": "path:line", "confidence": "found | uncertain" } ], "write_authority": [""], "money_touching_actions": [ {"tool": "", "action": "", "limit": "", "enforced_in": "code | prompt_level_only | none_found", "approval_gate": "", "source": "path:line"} ], "data_access": { "reads": [""], "scoping": "", "other_customers_reachable": "no | yes | uncertain", "other_customers_note": "", "source": "path:line" }, "escalation": { "triggers": [""], "mechanism": "", "enforced_in": "code | prompt_level_only | uncertain", "never_do": [""], "source": "path:line" }, "version_identifiers": { "model_id": "", "repo_commit": "", "prompt_files": [{"path": "", "sha256": ""}], "config_files": [{"path": "", "sha256": ""}], "toolset": {"tool_count": 0, "definition_source": ""} }, "uncertain": [""], "declaration": "Self-declared by the vendor's own tooling from the vendor's own repository. It is a declaration of intended capability, not evidence of behavior. Nothing in it has been independently observed." } } ``` Field notes: - `autonomy.mode`: `answer_only` if no tool changes anything, `recommend_only` if it drafts for a human, `bounded_action` if it acts within limits the code enforces, `open_action` if it acts with no enforced limit. - `financial_authority_usd`: the largest amount the agent can move in one action without a human. Always pair it with `financial_authority_basis`. When the basis is `no_limit_found` the number means nothing and the basis is the answer. Use `not_applicable` with `0` only when no tool touches money. - `capability_claims`: at least one. Ids are lowercase and three characters or more. - Every `source` is a repository path, with a line number when you have one. If you cannot cite it, it does not go in the file. - Keep `declaration` exactly as written. ## declared-actions.md Under one page: - The agent in two sentences. - Surfaces, one line. - A table of tools: name, mutates, touches money, limit, where the limit is enforced. - What it can read about customers other than the one it is talking to. - What triggers a handoff, and what it is told never to do. - The identifiers that pin this exact build. - Everything you marked uncertain. - This last line, verbatim: `Self-declared by the vendor's own tooling. Declaration, not evidence.` ## Check before you hand it over If you have the starter installed, the structural checks are mechanical: ```bash pip install git+https://github.com/agentfactfile/agent-factfile-starter python3 -m factfile_starter validate-declared-profile declared-profile.json ``` It exits nonzero on a `financial_authority_usd` with no basis, an entry with no `path:line` citation, a paraphrased `declaration`, a malformed digest, a missing `uncertain` array, or an excluded entry with no reason — and it warns when `uncertain` is empty. It cannot tell you whether you found every tool. By hand, with or without it: - Every registered tool appears in `tools`. Count the registrations, then count your rows. - Every mutating tool appears in `write_authority`. - Every limit says where it is enforced. - No number appears that you did not read in code or a prompt. - The file parses: `python3 -c "import json;json.load(open('declared-profile.json'))"`. ## Where this goes This is the intake for a dry run: a private test of the agent against the questions enterprise reviewers ask. The declaration says what the agent is allowed to do. The dry run finds out what it does. Two return paths, both fine: - Email both files to **hello@agentfactfile.com**. We reply with the questions a reviewer would ask about them, whether or not you go further. - Book **https://cal.com/tyecoleman/dry-run-scoping** and we build the declaration together on the call. Results go to the vendor and to nobody else. Nothing here is published.