A reviewable tool contract for smolagents: inputs, authority, evidence and recovery
Design one limited agent task around explicit tool behavior before expanding the number of tools it can use.
Choose a task small enough to explain
The smolagents project provides agent-building capabilities, including support for agents that express actions through code and options for isolated execution environments. These capabilities create useful possibilities, while the application must still decide which actions are permitted. This guide proposes a tool-contract review for a hypothetical agent that searches a fixed collection of public project notes. It contains no completed security assessment or performance measurement of a particular model, execution environment or deployment.
Write the task in one sentence: find relevant notes, return their identifiers and explain which passages support a short answer. Start with a single read-only tool and a bounded collection. Define the circumstances in which the agent should stop and ask for help. A small task makes it easier to connect an observed action to a permission, and it gives reviewers a manageable basis for deciding whether more capability is justified.
Describe the tool as a contract
A useful contract states the tool's purpose, accepted inputs, returned fields, possible failures and external effects. For the note-search example, inputs might include a query and a validated collection scope. Outputs might include note identifiers, source locations and passages. Specify what an empty result means and how a failure differs from a successful search with no matches. These distinctions help the surrounding application respond predictably when the agent encounters uncertainty.
Reviewers should be able to understand the contract without reading every line of the implementation. Explain how the scope is determined and which system owns that decision. A model-supplied collection name should not independently confer access to that collection. Validate inputs against the application's trusted state, and record the permissions needed by the actual execution process. Tool descriptions help the model choose actions, while enforcement needs concrete checks in the application and execution environment.
Distinguish instructions from retrieved material
Public notes, websites and tool responses may contain text that resembles a command. Treat such content as material to analyze, not as independent authority to change the task or expose other files. The tool contract should explain how returned content is labelled and how the agent is expected to cite it. Give the application a clear rule for which instructions originate from the user and which are merely quoted inside a source.
Use harmless fixtures to test this distinction. A sample note can contain a request to send an unrelated file, while the authorized task remains finding documentation passages. The expected behavior is to keep the note as evidence and continue within the original scope. Conduct this exercise in a controlled environment with public dummy data. The purpose is to observe a boundary, without attempting to exploit a third-party service or using real sensitive documents as test objects.
Constrain the execution environment deliberately
For an agent that can execute code, list the files, network destinations, packages and credentials it actually needs. Start with the minimum set that supports the chosen task. Review the available isolation mechanisms against the current project documentation and your deployment requirements. An environment being described as isolated does not establish that every configuration meets the same guarantees, so document the configuration and the assumptions it leaves outside its boundary.
Keep long-lived service credentials outside generated code and ordinary diagnostic output. If a tool needs an external service, consider how its access can be limited and revoked. Separate a tool's permission to read an existing record from permission to create or change one. These recommendations are design responsibilities for the surrounding application. They should not be interpreted as a claim that naming a tool or selecting a library automatically applies those restrictions.
Put limits on effort and define stopping behavior
Set a task budget in terms that can be observed, such as tool attempts, elapsed work or a permitted number of returned passages. Choose the actual limits according to the task and the cost of failure. Explain what the user sees when the budget is reached. A clear partial-result message can be more useful than repeated attempts that produce no new evidence while consuming resources and delaying human review.
Test a missing note, an unavailable tool and a result with an unexpected structure. Ask whether the agent recognizes that the operation failed, preserves what it already learned and stops at the intended boundary. Record the sequence of actions and the reason for each stop. Keep these cases in a regression set, because a change that improves ordinary task completion can still make failure handling less predictable.
Require evidence for conclusions and action outcomes
The final response should distinguish retrieved facts, the agent's synthesis and unresolved questions. Every important source-based claim should lead back to an identifiable note or passage. If no relevant material exists, the response should explain that limitation. A confident narrative cannot substitute for evidence that the tool actually returned. Review whether the response preserves qualifications from the source rather than quietly broadening them into general advice.
If the task later gains a write capability, require an observable outcome from the target system. A planned change, an attempted request and a confirmed result are different states. For operations that can partially succeed, define a way to query the target before retrying. Review the intended recipient, object and scope before consequential actions. This makes an eventual expansion of the tool set easier to reason about than introducing broad write access all at once.
Keep a compact, useful audit trail
An investigation record can include the task identifier, selected tool, validated input scope, result identifiers, outcome and stopping reason. Decide which fields are genuinely necessary before collecting complete prompts or source documents. Detailed debugging material may require a separate access policy and cleanup process. The audit trail should let a maintainer reconstruct relevant decisions without creating an uncontrolled second archive of every document the agent encountered.
Assign responsibility for reviewing failures and revoking a tool if its assumptions change. For example, a note-search service may begin returning a different format or a formerly read-only endpoint may gain additional behavior. Record the tool contract version alongside the agent configuration so that a later problem can be connected to the environment in which it occurred. This relationship is particularly useful when several tools evolve independently.
Expand capability through explicit acceptance decisions
Before adding a second tool, review the original task's ordinary cases, failure cases, access boundary and evidence quality. List the new behaviors the additional tool enables and the new failure paths it introduces. Preserve a small demonstration showing why the capability is needed, together with tests that could justify withdrawing it. Capability growth should leave a clearer operating record rather than merely a longer list of connected services.
The resulting agent may initially feel narrow, but its behavior is easier to explain and improve. A reviewer can inspect the contract, follow the evidence and understand what happens when a task cannot be completed. That is a practical foundation for useful autonomy: a limited set of actions, enforced authority, traceable outcomes and a recovery path that remains understandable to the people responsible for the system.
Primary sources: huggingface/smolagents official repository ↗. Checked on November 13, 2026.
Editorial note: An original COTCC site-team guide, written with AI assistance and checked against primary sources. Scenarios and acceptance criteria are editorial proposals, not reported deployments or benchmark results. Verify current project documentation for features, licensing and costs.
Discussion 0
Oldest firstSign in to join the discussion.
No public comments yet. Start the discussion.