moo.agent.agent_tools

Stage-2 PydanticAI tools — one async function per MOO command an agent can issue.

Each tool follows the same shape:

1. Build the command string (translate logic, ported verbatim from the old tools.py ToolSpec.translate callables).

2. await ctx.deps.limiter.wait() to respect the per-agent rate cap.

3. await ctx.deps.connection.request(cmd, async_wait_s=..., async_pattern=...) per the spec table in docs/specs/pydantic-ai-stage-2.md.

4. ctx.deps.on_window_append(f"> {cmd}") so the brain’s rolling window reflects what was sent.

5. Return the resulting MOO output string to the model.

Side-effecting tools (respond, done, teleport, page) follow slightly different shapes — see each function’s docstring.

The async-wait patterns for Celery-backed verbs live here as module-level re.Pattern constants. Their meanings are documented in the spec.

Functions

alias(ctx, obj, name)	Add an alias name to an object so players can refer to it by that name.
burrow(ctx, direction, room_name)	Atomic bidirectional dig: creates a forward exit to a new room, moves you into it, and wires the return exit automatically (opposite direction).
clear_topic(ctx, topic)	Clear The Dispatch Board and Survey Book entries for a specific topic.
close_(ctx, obj)	Close a container or door.
create_object(ctx, name[, parent])	Create a new object in the current room.
describe(ctx, target, text)	Set the description of an object or room.
dig(ctx, direction, room_name)	Create a new exit from the current room to a new destination room.
divine(ctx[, subject, of])	Consult the aether for random world objects.
done(ctx, summary)	Signal that the current goal is fully complete.
drop(ctx, obj)	Drop an item from inventory into the current room.
exits(ctx[, target])	Show the exits for a room.
go(ctx, direction)	Move through an exit in the given direction.
look(ctx[, target])	Look at the current room or a specific object.
lore_character(ctx, name)	Look up source material for a real-world character by name (e.g. a Simpsons character).
lore_room(ctx, name)	Look up source material for a real-world place by name (e.g. a Simpsons location).
move_object(ctx, obj, destination)	Move an object to a different room or container (changes its location).
obvious(ctx, obj)	Mark an object as obvious so it appears in room descriptions.
open_(ctx, obj)	Open a container or door.
page(ctx, target, message)	Send a page (private message) to another player.
place(ctx, obj, prep, target)	Set a spatial relationship between an object and a target in the same room.
post_board(ctx, topic, room_ids)	Post a room ID list to The Dispatch Board for a specific topic.
put(ctx, item, container)	Put an item inside a container (moves it into the container).
raw(ctx, command)	Send a raw MOO command verbatim.
read_board(ctx, topic)	Read the room ID list from The Dispatch Board for a specific topic.
read_book(ctx, topic[, room_id])	Read entries from The Survey Book for a specific topic.
respond(ctx, message)	Say something without acting on the environment.
rooms(ctx)	List every room instance in the world as a flat #N/name list.
select_tools(names)	Build the agent's tool list from a per-agent whitelist.
show(ctx[, target])	Inspect an object or the current room in full detail — exits, contents, properties, verbs, IDs.
survey(ctx[, target])	Lightweight room inspector.
tag_source(ctx, obj, sources)	Record which krustylu source(s) an object was derived from, as the list property 'krustylu_sources' (e.g. ['location:moe-tavern'] or ['character:moe-szyslak']).
take(ctx, item[, source])	Take an item from the room into your inventory.
teleport(ctx, destination)	Teleport directly to a room by #N or name, without following exit chains.
tunnel(ctx, direction, destination)	Add a return exit from the current room back to an origin room.
write_book(ctx, room_id, topic, entry)	Write an entry to The Survey Book for a specific room and topic.
write_verb(ctx, obj, verb, code[, dspec, on])	Create or overwrite a verb on an object.