Tools
The Dejo MCP server gives your agent 16 tools. You don't call them yourself: you ask in plain words, and each tool's result tells your agent what to do next. This page is for when you want to know what is going on.
Every tool returns a result with ok. When something fails, the result has ok: false and an error that says what happened and what to do.
The four your agent uses most
| tool | what it does |
|---|---|
dejo_run | Does a website task. Called first, every time. If Dejo knows the task, the whole task finishes in this one call. If not, it says so. |
dejo_act | Does one thing in the browser (click, fill, open a page) and returns what changed. Used only while exploring. |
dejo_read | Looks at the page without changing it. kind="page" lists the controls, each with a ref to act on. |
dejo_save | Saves what your agent just did as a route, with a check on every step. Next time the same task is one dejo_run. |
dejo_run
dejo_run(site, task?, url?)
site: the website, as a domain or a full URL.task: which task, in the plain words it was saved under. Only needed when a site has more than one. Close wording is matched too.url: where the first step should go, if it is different from what was learned.
What comes back:
| result | meaning |
|---|---|
ok: true | Done. answers holds what the route read. model_calls is always 0. |
known: false | Dejo has never been here. Explore with dejo_act and dejo_read, then dejo_save. |
needs_task: true | The site is known, this task is not. tasks lists the saved ones. |
needs_repair: true | The site changed and one step broke. repair describes it and lists the controls on the page now. |
needs_login: true | The site wants a sign-in. See Signing in. |
page_error | The site answered with an error page (404, 403, 500...). The page is missing or not shared with this account, so nothing is read and nothing is marked broken. |
blocked: true | A captcha. Dejo stops and does not try to solve it. Clear it yourself once and run again. |
stale: true | Most of the steps broke, so the site was rebuilt. Dejo drops the route but keeps what it knew about the site, so relearning is cheaper than the first visit. |
When a task is new, pages_known lists the pages Dejo has already seen on that site, so your agent starts from those instead of hunting.
dejo_act
dejo_act(intent, action, ref?, value?, to?)
intent: why, in plain words, like "open this month's invoice". It is stored, and a future repair is explained by it.action: one of 35 actions.ref: which element: areffromdejo_read, ausestring fromdejo_map(such asrole=button|Sign in), or a CSS selector.value: the text, key, option, URL or seconds the action needs.to: the second element, fordrag.
The actions:
| group | actions |
|---|---|
| clicking and pointing | click, double_click, hover, tap, drag, focus, blur, scroll_to |
| fields | fill, type, clear, press, check, uncheck, set_checked, select, upload, select_text |
| the page | goto, back, forward, reload, scroll, new_tab, switch_tab |
| waiting | wait_for (the right way to wait), wait (last resort) |
| the route | restart_trail, dismiss_when_seen, set_time |
| for people | screenshot, highlight, hide_highlight |
| escape hatches | evaluate (your own JavaScript, never saved into a route), dispatch_event (last resort) |
wait_for takes what to wait for as kind:subject: element:…, in_frame:…, gone:…, text:…, url:…, or idle.
restart_trail matters before saving. Everything your agent does is written down, including wrong turns, and a saved mistake is replayed forever. Explore however you like, then restart and walk the task once, cleanly.
dejo_read
dejo_read(kind="page", ref?, attribute?, remember?, intent?)
| kind | gives back |
|---|---|
page | the controls on the page, each with a ref (up to 60) |
text | the words inside one element. The one you usually want. |
all_text | the words in every matching element, for a table or list |
value, checked, visible, enabled, editable | the state of a field or control |
attribute | one attribute, such as href |
count | how many elements match |
url, title | the current page's address and title |
console_errors, failed_requests | why a page is broken or empty |
page_text | the whole page's text. For looking around only. |
Pass remember: true with an intent on the read that is the answer (the number, the status, the total). Then dejo_run returns it on every later run.
dejo_save
dejo_save(task, answer?)
task: what was done, in plain words, like "download this month's invoice".answer: the exact text your agent is about to report, if the task had one. Dejo finds the element that shows it and stores every way of finding it again.
Repairing and remembering
| tool | what it does |
|---|---|
dejo_repair(site, step_index, ref?, css?, task?) | Fixes the one step that broke, after dejo_run returned needs_repair. Pass the ref of the right control from repair.candidates; Dejo stores every durable way of finding it. |
dejo_map(site, path?) | What Dejo saw on a site before: which pages, and the controls on each. It says when each page was seen. |
dejo_note(site, fact?, needs_login?, needs_2fa?, account?) | Remembers a fact that is not a step, like "the export takes two minutes". Facts survive a redesign. |
dejo_show(site) | The saved route for a site, step by step. |
dejo_sites() | Every site Dejo remembers, with how well each route is holding up. |
dejo_forget(site) | Forgets a site completely. The next run has nothing to follow and says so. |
Signing in and profiles
| tool | what it does |
|---|---|
dejo_login(site) | Opens a real browser window so you sign in, however the site asks. |
dejo_login_done(site, confirmed?) | Closes that window once you are signed in. Dejo checks the window first. |
dejo_profile(name?) | Switches to another signed-in identity, such as vendor or admin. With no name, lists them. |
Details: Signing in.
Sharing between agents
Agents on one machine can hand routes to each other.
| tool | what it does |
|---|---|
dejo_share(site, task?) | Leaves a route where other agents can find it. The steps, locators, checks and notes travel. Anything typed into a field, and which account was used, never do. |
dejo_borrow(site, task?, force?) | Copies a shared route into this agent's own memory. |
dejo_commons() | Every route any agent has shared, and who left it. |
The same things from a terminal
The dejo command does most of this without an agent:
dejo run "count open issues" --site github.com
dejo sites
dejo show github.com
dejo map github.com
dejo login --site github.com
dejo forget --site github.com
dejo doctor
dejo --help lists every command.
FAQ
Why does Dejo have only two tools for browsing?
Every action goes through dejo_act and every read through dejo_read. Picking the right tool is the most fragile part of an agent's day, and more tool names make it worse.
Does my agent have to call these tools by name?
No. Ask in your own words. The Dejo server tells your agent to call dejo_run first for any website task, and each result says which tool to call next.