Agent-Exposed Docstring Conventions

STATEK agents work by writing Python against tools, objects, classes, and values in their workspace. Docstrings are the interface text the model sees when prompts expand {brief_tools}, {tools}, or {detailed_tools}, and when an agent calls brief(...) or docstr(...) while inspecting the workspace.

Treat agent-exposed docstrings like a small API contract. They should say what the callable or object is for, how to call it, what it returns, and which side effects or approvals matter.

Recommended Shape

STATEK parses Google-style docstrings for functions and classes. Use:

• a first paragraph with the short operational purpose
• optional extra detail after a blank line
• Args: for every public function parameter except self and cls
• Returns: for the value the next Python step receives
• Raises: for expected failures the agent can handle
• Example: for short runnable usage when it prevents ambiguity
• class Attributes: for object members the agent may inspect
• class Tags: for short metadata labels that should appear in full class docs

Keep the first paragraph short. It becomes the most compact description in brief output and tool listings.

Read-Only Tools

Use read-only tool docs to explain selection criteria and return shape. Do not bury required arguments in prose.

from statek import tool
 
@tool
def find_open_slots(calendar, after, duration_minutes=30, **kwargs):
    """Find available calendar slots after a given time.
 
    Args:
        calendar: Calendar object to search.
        after: Earliest acceptable slot start.
        duration_minutes: Required slot length.
 
    Returns:
        A list of candidate slots ordered from earliest to latest.
    """
    return calendar.find_open_slots(
        after=after,
        duration_minutes=duration_minutes,
    )

This gives the model enough information to call the tool from Python:

slots = find_open_slots(calendar, after=meeting.ends_at, duration_minutes=45)

Side-Effecting Tools

For tools that write state, send messages, call external systems, or spend money, state the side effect and the approval expectation in the docstring. The tool implementation still has to enforce policy.

from statek import tool
 
@tool
def send_confirmation(user, meeting, approval_id, **kwargs):
    """Send the approved meeting confirmation to the user.
 
    Call this only after a human approval record exists for the exact
    meeting time and recipient.
 
    Args:
        user: Recipient user object.
        meeting: Meeting to confirm.
        approval_id: Durable approval record id authorizing this send.
 
    Returns:
        Delivery receipt id from the messaging service.
 
    Raises:
        PermissionError: The approval does not cover this user and meeting.
    """
    approval = approvals.get(approval_id)
    approval.require_covers(user=user, meeting=meeting)
    return message_service.send_meeting_confirmation(user, meeting).receipt_id

Good side-effect docs name:

• what changes outside the Python process
• what approval, idempotency key, or policy state must exist first
• what durable receipt or object is returned
• expected exceptions the agent can recover from

Prompt Placeholders and Inspection

Prompt placeholders consume the same parsed docs:

• {brief_tools} inserts compact tool descriptions.
• {tools} inserts normal tool descriptions.
• {detailed_tools} inserts Python-style tool details.

System documentation tools are available for code-first inspection:

brief(calendar)
docstr(Calendar, "reserve_slot")
docstr(send_confirmation)

brief(...) prints the short form. docstr(...) prints full Python-style documentation for a tool, class, object instance, or named method.

Classes and Context Objects

Objects passed in agent context should document the members and methods the agent is expected to use. Class docs can include Attributes:, Tags:, and public methods with their own docstrings.

from dataclasses import dataclass, field
 
@dataclass
class Calendar:
    """Calendar workspace for reading events and reserving slots.
 
    Attributes:
        timezone (str): IANA timezone used for displayed times.
        owner_id (str): Durable id of the calendar owner.
 
    Tags:
        scheduling
        user_visible
 
    STATEK-ACL:
        +*
        -internal_notes
        -update_*: MessageDispatcher
    """
 
    timezone: str = field(metadata={"doc": "IANA timezone for event times."})
    owner_id: str = field(metadata={"doc": "Durable calendar owner id."})
    internal_notes: str = field(default="", metadata={"doc": "Private notes."})
 
    def open_slots(self, day):
        """Return available slots for a day.
 
        Args:
            day: Date to inspect.
 
        Returns:
            Available slots sorted by start time.
        """
        return self._open_slots(day)
 
    def reserve_slot(self, slot, title):
        """Reserve an available calendar slot.
 
        Args:
            slot: Slot returned by open_slots.
            title: Meeting title to store.
 
        Returns:
            The created meeting.
        """
        return self._reserve(slot, title)

Dataclass field metadata with the key doc is merged into generated class docs. Explicit Attributes: entries can clarify or override introspected field descriptions when needed.

Separate Tool Wording

Use VARIANTS/:.../TOOL:... when the default Python documentation and the agent-facing tool wording should differ. STATEK's tool documentation parser selects the TOOL variant and falls back to the default variant when a tool variant is missing.

from statek import tool
 
@tool
def reserve_slot(calendar, slot, title, **kwargs):
    """VARIANTS/:Reserve a slot in the calendar model./TOOL:Reserve an approved available slot.
 
    Args:
        calendar: Calendar object to update.
        slot: VARIANTS/:Slot instance./TOOL:Slot previously returned by open_slots.
        title: Meeting title.
 
    Returns:
        Meeting: VARIANTS/:Created meeting./TOOL:Created meeting with durable id and start time.
    """
    return calendar.reserve_slot(slot, title)

Variant names are case-insensitive and may also be used in class descriptions, attribute descriptions, return descriptions, raises descriptions, and examples.

Brief Signatures With Types

Brief output normally omits argument types. Use @docs_style(brief_types=True) when the compact form is ambiguous without types.

from statek import docs_style, tool
 
@tool
@docs_style(brief_types=True)
def render_calendar(month: "date") -> str:
    """Render a calendar view for a month.
 
    Args:
        month (date): Month to render.
 
    Returns:
        str: Plain-text calendar view.
    """
    return calendar_renderer.render(month)

In brief output, this can show render_calendar(month: date). Full docstr(...) output already includes types where they are available.

Documentation ACLs

Class docstrings can include a STATEK-ACL: section to filter attributes, properties, and methods shown by formatted class documentation.

class CustomerRecord:
    """Customer account visible to support agents.
 
    Attributes:
        name (str): Display name.
        email (str): Contact email.
        secret_field (str): Internal security marker.
 
    STATEK-ACL:
        +*
        -secret_field
        -update_*: MessageDispatcher
    """
 
    def update_email(self, email):
        """Update the customer's contact email.
 
        Args:
            email (str): New email address.
 
        Returns:
            None: Updates the record in place.
        """

ACL rules use:

• +* to grant every name by default
• -* to deny every name by default
• exact names such as -secret_field
• prefixes such as -update_*
• scoped rules such as -update_*: MessageDispatcher

Rules are evaluated in order and the last matching rule wins. Scoped rules apply only when the current agent name matches the scope. A scoped rule is skipped for other agents.

If no class-level STATEK-ACL is defined, formatting code can use the fallback ACL exposed by StatekSettings.default_acl. When a class has its own STATEK-ACL, the class-level rules take precedence over that fallback.