ai-agent-channel

open_obligations

Read-only

List open action-required obligations addressed to a role, with age and idle days, to reveal forgotten debts that still need resolving.

Instructions

List open obligations: action_required messages with status='open' addressed to a role (defaults to your own role). These are the debts that still need resolve_message. Each carries 'age_days' (since it was raised) and 'idle_days' (since it last MOVED — a status transition, a resolve, a reopen). Idle is the number that finds forgotten work: an old debt worked on yesterday is healthy, a young one nobody has touched is not, and age alone cannot tell them apart. Nothing is ever auto-closed on either number. Optional 'fields' projects the response: a list of field names, or the single value 'headers' for the usual listing set (everything except the bodies). Omit it and the full record comes back. Use it when a listing over a long history would otherwise be too large to return — bodies dominate the size, and a 'which messages' question rarely needs them; fetch the ones you want individually afterwards.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No
`fields`	No
`to_role`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With only readOnlyHint=true in annotations, the description adds substantial behavioral depth: the distinction between age_days and idle_days, the fact that nothing is auto-closed, the default role default, and the fields projection behavior. This goes well beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by field semantics and usage guidance. The idle_days explanation is slightly discursive but serves an educational purpose; overall it earns its length without being bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists and the readOnlyHint annotation is present, the description covers all operational aspects an agent needs: what is listed, what fields are returned, how projection works, the default role behavior, and when to use the tool. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the parameter semantics. It thoroughly explains the 'fields' parameter, including 'headers' and omit behavior, and explains that to_role defaults to the caller's role. 'limit' is left to the schema's integer/default, which is acceptable since it's straightforward.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and defines the resource precisely: action_required messages with status='open' addressed to a role, defaulting to the caller's role. It also clarifies these are obligations that need resolve_message, which distinguishes it from general message listing or search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context: use it when a listing over long history would be too large to return, and project fields for 'which messages' questions rather than pulling full bodies. It doesn't explicitly name sibling alternatives like list_messages or search_messages, but the intended boundary is mostly inferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.