soma — protocol for agent rhythm and vows

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

With no annotations, the description carries the full burden. It does disclose two genuinely useful behavioral traits: the claim is exclusive ('эксклюзивно'), implying a lock/removal from the queue, and payment may be required for priced work. However it says nothing about permissions, failure modes, whether a claim can be released, or what happens on a duplicate claim.

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

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

Two compact sentences with the core action front-loaded and no filler. It is efficient, though the phrase 'получить контекст под бюджет' is cryptic enough that brevity shades into under-specification.

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

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

An output schema exists, so return values need not be described, but for a mutating, exclusive-claim tool with zero annotations and 0% parameter coverage the description is too thin. It omits the semantics of id/agent, error conditions, and the release/lock lifecycle an agent would need.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: 'квитанция' maps loosely to the optional payment parameter and gives the condition under which it is needed. The required id and agent parameters are never explained, leaving half the contract undocumented.

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

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

The description states a specific verb and resource — 'Забрать конверт из очереди' (claim an envelope from the queue) — plus the exclusivity and context-retrieval outcome, so an agent can tell it apart from list-oriented siblings like soma_inbox. It does not explicitly name any sibling to sharpen the boundary, keeping it just short of a 5.

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

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

There is no guidance on when to call this versus alternatives such as soma_inbox (peek) or soma_route. The only conditional ('if the work has a price, a receipt is required') is a parameter-level note about payment, not when/when-not usage guidance.

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

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

No annotations are present, so the description carries full behavioral burden. It implies a state-changing completion ('close') and that a result is supplied, but omits permissions, side effects, reversibility, or any rate limits.

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

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

A single short sentence with no filler, but it is under-specified for a tool with three parameters and no schema descriptions. It is front-loaded yet too terse to earn its place as sufficient guidance.

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

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

Given a three-parameter mutation tool with no annotations and 0% schema coverage, the description is far too sparse. Although an output schema exists, the description still fails to cover parameter semantics, usage context, or behavioral traits.

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

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

Schema description coverage is 0% for all three parameters (id, agent, result). The description only echoes 'result' without explaining its format or the roles of id and agent, adding no meaning beyond the schema.

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

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

States a specific verb ('Закрыть' / close) and resource ('конверт' / envelope) plus the instrument ('результатом работы' / with the work result). It does not differentiate from siblings like soma_send or soma_route, but the action is clear enough for an agent in this ecosystem.

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

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

Provides no when-to-use guidance, no prerequisites, and does not mention any alternative tools such as soma_send or soma_route. The agent must infer usage entirely.

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

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

No annotations are provided, so the description carries the full burden. It hints that envelopes involve signature verification and that context is assembled under a token budget, which is useful behavioral color, but it does not state read-only vs. mutating semantics, auth requirements, pagination, or side effects.

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

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

The single sentence is short, but it is under-specified rather than concise: it spends its words on an oblique framing instead of stating the tool's action or scope.

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

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

An output schema exists, so return values need not be re-explained, but for a tool with two undocumented parameters and no annotations the description leaves the agent unable to determine purpose, usage, or parameter behavior. It is far short of complete.

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

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

Schema description coverage is 0% for both parameters ('agent', 'limit'), and the description adds no information about what these parameters mean or how they shape the result. Nothing compensates for the undocumented schema.

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

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

The description describes what the agent will receive (envelopes, signature verification, token-budgeted context) rather than stating what the tool does or returns as an action on the 'inbox'. No clear verb+resource framing, and it does not distinguish soma_inbox from siblings like soma_route or soma_send.

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

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

There is no indication of when to call this tool, when not to, or which sibling to use instead. The phrase 'what awaits the agent' implies a pull/inspect operation but never states the condition for using it.

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

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

No annotations are provided, so the description carries the full burden. It does disclose one useful behavioral trait: if no candidate exists, an 'honest refusal reason' is returned rather than an empty result. However, it says nothing about authorization/mandate requirements, determinism, or what the 'id' refers to, leaving significant behavioral gaps.

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

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

Two short, front-loaded sentences with no filler; the core action leads and the failure behavior follows. Efficient and appropriately sized for the amount of information conveyed.

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

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

An output schema exists, so return values need not be spelled out. But the single required 'id' parameter is undocumented in both schema and description, and the described selection criteria (capability/mandate/price) have no corresponding inputs, leaving an agent unable to know what to pass for a routing call.

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

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

There is a single parameter ('id') with 0% schema description coverage, and the description never explains it. Worse, the criteria the description names (capability, mandate, price) do not correspond to any declared parameter, so the text implies inputs the schema does not expose, which is potentially misleading.

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

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

States a specific verb and resource ('Подобрать исполнителя' – match/select an executor) with explicit selection criteria (capability, mandate, price). It is clear what the tool does, but it makes no attempt to distinguish itself from siblings like soma_claim or soma_verify, so it falls short of a 5.

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

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

There is no statement of when to use this tool versus the alternatives (soma_claim, soma_send, etc.), nor any prerequisites. The only contextual sentence concerns the failure case (no candidate), which is behavioral rather than usage guidance.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that the envelope is signed and placed into a queue, which implies asynchronous processing, but it omits permissions, idempotency, failure behavior, and what happens after queuing.

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

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

The description is compact and front-loads the action, with no wasted sentences. However, the dense field list is not structured as a parameter guide, which limits readability for a 12-parameter tool.

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

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

Given 12 parameters, no annotations, and 0% schema description coverage, the description is too thin. It mentions signing and queuing but does not cover required/optional distinctions, defaults, authorization, or operational constraints needed for confident invocation.

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

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

Schema description coverage is 0% across 12 parameters, so the description must compensate. It maps conceptual terms to some fields such as goal, task, recipient, token budget, mandate, and price, but leaves sender, ttl_s, visibility, context_query, cost_usdc, max_cost_usd, and others unexplained.

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

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

The description states a specific verb and resource: "Отправить конверт агенту" (send an envelope to an agent), and names key payload concepts such as goal, task, recipient, token budget, mandate, and price. It is clear what the tool does, though it does not explicitly distinguish itself from siblings like soma_route or soma_claim.

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

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

It does not say when this tool should be used instead of siblings such as soma_route, soma_claim, or soma_inbox. There is no when-to-use, when-not-to-use, or prerequisite guidance beyond the implied action of sending an envelope.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only state report but never states that it has no side effects, whether it requires auth, or how expensive/rate-limited it is — all left unspecified for a hub-inspection call.

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

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

A single short sentence with no filler, and the leading phrase 'Состояние хаба' front-loads the core purpose. It is a fragment rather than a full clause, but nothing is wasted.

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

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

For a zero-parameter stats tool with a full output schema, the description does not need to explain return values, and it does list the main content categories. However, it still omits any indication of when this inspection is appropriate versus the sibling tools, leaving a gap for an agent choosing between seven soma_* calls.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies the call is unfiltered and global, which is consistent with an empty argument object.

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

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

Although it uses a noun phrase rather than a verb, it enumerates exactly what the tool reports: hub state with envelopes by status, facts, links, and cold artifacts. This is specific enough to distinguish it from the action-oriented siblings (soma_claim, soma_send, soma_verify), though it never explicitly says it is a read-only report.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the six sibling tools. The agent must infer usage purely from the tool name and the returned-content list.

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

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

With no annotations, the description carries the behavioral burden and discloses key traits: verification is offline, the algorithm is Ed25519, and the public key is embedded with the signature. It does not describe error behavior or explicitly confirm read-only safety, but the output schema likely covers return values and the core invocation behavior is clear.

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

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

A single sentence, front-loaded with the action verb, with no redundant or filler content. It is appropriately sized for a simple one-parameter verification tool.

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

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

The tool is simple and an output schema exists, so return values need not be explained. The description covers purpose and verification mechanism but leaves input format details undocumented, which is a clear gap given 0% schema description coverage for envelope_json.

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

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

Schema description coverage is 0% for the single parameter, so the description must compensate. It implies the envelope contains a signature and public key, but provides no field names, JSON structure, or encoding details needed to construct a valid envelope_json.

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

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

The description states a specific verb ('Проверить подпись') and resource ('конверта'), plus scope ('офлайн') and algorithm ('Ed25519'). The action is clearly distinct from sibling operations like soma_send, soma_route, or soma_claim, so an agent can identify it without opening the schema.

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

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

The description gives no when-to-use guidance, no when-not-to-use conditions, and does not name any alternative sibling tool. 'Офлайн' is a capability note, not routing guidance for choosing this tool over others.

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