ai-agent-channel

open_obligations

List open obligations addressed to a role so action-required messages still needing resolve_message get found. Shows age since raised and idle time since last activity to reveal stalled work.

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 exactly as before. 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.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the default role scoping, the crucial constraint that 'Nothing is ever auto-closed on either number', and the projection default that omitting 'fields' returns the full record. It omits auth/permission requirements and pagination behavior (limit), so it is strong but not exhaustive.

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

Conciseness3/5

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

The purpose and scoping are front-loaded, which is good, but the middle passage on idle vs age ('an old debt worked on yesterday is healthy, a young one nobody has touched is not, and age alone cannot tell them apart') is discursive for a tool description, and since an output schema exists much of the field-semantics explanation is redundant.

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

Completeness4/5

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

For a 3-param read tool with an output schema, the description supplies purpose, default scoping, projection mechanics, and a key behavioral guarantee about auto-closing. Completeness is undercut only by the unexplained 'limit' parameter.

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 compensate and it does for two of three parameters: it explains 'to_role' (defaults to your own role) and 'fields' in detail (list of names or the single value 'headers', default returns full record). The 'limit' parameter is left entirely unexplained, which is the one gap.

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?

It states a specific verb and resource ('List open obligations') and then defines the term precisely: action_required messages with status='open' addressed to a role. This distinguishes it from generic siblings like list_messages or read_inbox without needing to open any schema.

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?

It explicitly ties itself to the resolve_message flow ('the debts that still need resolve_message') and gives a clear condition for using the fields projection ('when a listing over a long history would otherwise be too large'). It does not, however, state when to prefer this over list_messages or search_messages, so routing is inferred rather than explicit.

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