COMPEL Specialization — AITE-ATS: Agentic AI Systems Architect Expert Artifact Template 2 of 5
How to use this template
Populate one instance per tool. The specification is the authoritative description of what the tool does, who may call it under what conditions, what inputs it accepts, what the runtime does after execution, and what the tool costs to invoke. The policy engine, the tool wrapper, the observability schema, and the security review all read from this specification; the specification is the source of truth.
Store the populated specifications in the repository alongside the agent’s code (e.g., agent/tools/specs/*.yaml). Version them with the agent. A tool without a specification is not callable; the CI check that enforces this is the central discipline.
Tool-Use Constraint Specification
Identity
| Field | Value |
|---|---|
| Tool ID | stable identifier, e.g., T_READ_FILE |
| Tool name (as seen by model) | read_file |
| Specification version | 1.0 |
| Last updated | YYYY-MM-DD |
| Tool owner (role) | role name |
| Security reviewer (role) | role name |
1. Purpose
One to two sentences describing what the tool does and the architectural need it serves. Avoid marketing language. Describe the current capability, not the intended capability.
Example: Reads the contents of a single file under the task’s declared scope and returns the text. Used by the agent to inspect source code, configuration, and documentation within the sandboxed workspace.
2. Reversibility and blast radius
| Field | Value |
|---|---|
| Reversibility | read-only / reversible write / conditionally reversible / irreversible |
| Blast radius | one-sentence description of the worst-case consequence of a single bad call |
| Recovery mechanism (if reversible) | description |
For conditionally reversible tools (e.g., commit to a branch), name the conditions under which reversal is possible and the time window.
3. Authorisation predicate
The authorisation predicate is the condition the policy engine evaluates before the tool executes. Write as a single declarative sentence with its clauses enumerated.
Example: The agent may call read_file when (a) the agent’s identity has the filesystem_read capability; (b) the path is under the session’s declared task scope; (c) the path does not match the protected-paths list; (d) the path does not contain parent-directory traversal sequences.
| Field | Value |
|---|---|
| Policy-engine module | e.g., policies/tools/read_file.rego |
| Decisions returned | allow / deny / require_human_approval |
| Refusal reasons (for model feedback) | enumerate |
4. Input schema
Every parameter has a declared type, constraint, and rationale.
| Parameter | Type | Constraints | Required | Rationale |
|---|---|---|---|---|
| path | string | matches ^[a-zA-Z0-9_/.-]+$, max 1024 bytes | yes | restricts to printable ASCII path characters |
| encoding | string | one of utf-8, utf-16 | no; default utf-8 | explicit handling of non-UTF-8 content |
| Field | Value |
|---|---|
| Schema file | e.g., schemas/tools/read_file.json |
| Schema version | 1.0 |
| Validation library | e.g., ajv / pydantic / jsonschema |
5. Post-execution verification
Checks the runtime performs on the tool’s return value. Verification failures trigger the configured response (rollback, refusal-to-surface, escalation).
| Check | Purpose | Failure response |
|---|---|---|
| result size ≤ 10 MB | prevent context explosion | truncate; emit result.truncated |
| result is valid UTF-8 (for text tools) | integrity | replace invalid bytes; emit result.encoding_coerced |
| result does not match credential regex battery | secret-exposure defence | redact matching spans; emit result.redacted |
Add tool-specific checks as needed.
6. Resource caps
| Resource | Cap | Scope | On-exceed behaviour |
|---|---|---|---|
| Invocation count | e.g., 200 | per session | deny subsequent calls; emit cap.exceeded |
| Concurrent invocations | e.g., 3 | per agent | queue; emit cap.queued |
| Total data returned | e.g., 50 MB | per session | deny; emit cap.data_exceeded |
| Monetary cost (if applicable) | e.g., USD 5.00 | per session | deny; emit cap.cost_exceeded |
| Latency budget | e.g., 30 seconds | per call | cancel; emit cap.latency_exceeded |
7. Observability emissions
Structured events the runtime must emit. Schema is stable across the tool registry; fields below are the minimum.
| Event | When | Fields |
|---|---|---|
tool_call.started | before execution | tool_id, call_id, session_id, correlation_id, params_hash, authorisation_decision |
tool_call.completed | on success | tool_id, call_id, duration_ms, result_size, verification_outcome |
tool_call.failed | on failure | tool_id, call_id, duration_ms, error_class, error_message (redacted) |
tool_call.denied | on policy denial | tool_id, call_id, reason |
Redaction rules are inherited from the organisation’s PII policy and applied at emission.
8. Dependencies and side effects
| Dependency | Nature | Failure mode | Circuit-breaker ref |
|---|---|---|---|
| external API / database / filesystem | description | timeout / 5xx / rate limit | ref |
For tools with side effects on shared systems, name every system touched and describe how a failure in that system is surfaced to the agent and to the operator.
9. Security review
| Field | Value |
|---|---|
| OWASP Top 10 Agentic mapping | e.g., LLM06 Excessive Agency; LLM01 Prompt Injection if tool reads external content |
| MITRE ATLAS mapping | e.g., AML.T0051 if applicable |
| Threat-model review date | YYYY-MM-DD |
| Residual risk statement | one paragraph |
10. Change log
| Date | Version | Change | Reviewed by (role) |
|---|---|---|---|
| YYYY-MM-DD | 1.0 | initial specification | security reviewer role |
Retirement
When the tool is retired from the registry, this specification is retained for the agent’s deployment life plus the organisation’s records-retention period. A tool specification that appears in any live agent’s registry cannot be deleted.
End of Tool-Use Constraint Specification template.