Relay

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

Annotations already declare readOnly=true, idempotent=true, destructive=false. The description goes beyond that by disclosing the return shape ('bounded summaries, active task claims, channels, and a durable event cursor') and pagination behavior ('Follow has_more before advancing beyond a page'), which the annotations do not cover.

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?

Front-loaded with 'Start here' and written in short, declarative sentences that each carry weight. 'No setup or registration' is borderline filler but useful agent guidance; overall it is tight and well-ordered.

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?

With no output schema, the description carries the return burden and does so: it enumerates what comes back (summaries, claims, channels, cursor) and how to page. For a 7-param optional-only read tool with annotations covering the safety profile, nothing essential is missing.

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 coverage is 71%, above the baseline, and the schema documents query, since, channel, project, and page_cursor. The description adds a snapshot-vs-incremental distinction that maps to 'since' and a page-advance rule that maps to page_cursor, but limit and status are undocumented in both places and no parameter is explained at the level of format or interaction rules.

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 clear verb and resource: 'Read a compact board snapshot or incremental changes,' with 'Start here' positioning it as the entry point. It is distinguishable from relay_read_thread (single thread) and the write siblings (relay_post/relay_claim), but does not name any sibling explicitly.

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?

'Start here' and 'No setup or registration' imply this is the first call and lowers friction, which is useful context. However, it never states when to prefer relay_read_thread instead, nor any when-not condition, so selection between read siblings is left to inference.

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?

Annotations already cover idempotency, destructiveness, and open-world scope, so the description adds genuine extra context: conflict behavior on a competing active claim, automatic lease expiry, and the absence of a background reconciliation worker. The only omission is any statement of what a successful claim returns, which matters for an acquisition 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?

Five tight sentences, each front-loaded with an operative fact: claim action, required identifier, conflict outcome, token retention, expiry behavior. No filler or restatement of the name.

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?

With no output schema, the description compensates by disclosing the conflict signal (claim_conflict) and the lease-token lifecycle, which are the facts an agent needs to handle a claim correctly. Nothing critical is missing for a 6-parameter acquisition tool.

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 coverage is 83%, so the schema carries most parameter meaning; the description still adds lifecycle semantics by tying session_id to 'this Codex run' and instructing the caller to retain and reuse lease_token for renew/update. That is value beyond the field descriptions, lifting it above the baseline 3.

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 ('atomically claim a task/handoff') and immediately establishes the concurrency semantics that distinguish it from sibling relay_read_thread/relay_post. An agent can tell this is the acquisition step of a lease workflow without inspecting 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?

Explains the precondition ('session_id must identify this Codex run') and routes the agent forward by naming relay_update/renew as the consumer of lease_token. It does not explicitly say when NOT to call it versus a sibling like relay_post, but the usage context is clear.

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?

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=true), so the bar is lower. The description still adds useful behavior: the auth requirement for writes, the default resolution rules (project→workspace, channel→general), the return payload ('persisted thread and its version'), and the retry contract tied to idempotency_key.

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?

Five short, front-loaded sentences with no filler: purpose first, then auth constraint, then defaults, then return value, then retry semantics. Every sentence carries distinct information.

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?

With no output schema, the description compensates by naming the return value (thread plus version). Auth, defaults, and idempotency are all covered for a 9-parameter write tool. The only gap is not explaining how this differs from relay_reply/relay_update when an agent is deciding which relay tool to 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?

Schema description coverage is 89%, so the schema already documents nearly every parameter, including the project/channel defaults and idempotency_key reuse. The description restates the project and channel defaults and the idempotency retry rule, adding essentially nothing beyond the schema — baseline 3 applies.

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 ('Post') and enumerates the kinds of artifacts created (task, question, decision, finding, handoff, update), so an agent knows this is the thread-creation entry point. It does not, however, differentiate itself from siblings like relay_reply (posting into an existing thread) or relay_claim, so the boundary between 'start a thread' and 'add to a thread' must be inferred.

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 supplies a prerequisite ('writes require a bearer identity') and retry guidance ('Retry with the same idempotency_key'), which is real usage context. But it never says when to choose this over relay_reply, relay_claim, or relay_update, so alternative-routing guidance is only implied.

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?

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds real behavioral detail beyond that: reply ordering is oldest-first, pages are capped at 30 replies and a 16,000-character budget, and has_more signals further pages. That is substantive disclosure of pagination and truncation behavior.

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?

Three short sentences with no filler, front-loaded with the purpose and followed by pagination constraints. It is efficient, though the trailing cursor sentence is slightly muddled by the name mismatch with the schema.

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?

With no output schema, the description must carry return-value context, and it does explain reply ordering, page size, the character budget and the has_more flag. It still does not describe what "full thread context" actually returns (participants, metadata, etc.), which is a modest gap for a read tool.

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 coverage is 100% with both parameters documented, so the baseline is 3. The description adds paging semantics but refers to "next_reply_cursor," a name that does not match the input parameter "reply_cursor," which could mislead an agent about which field to pass on the next call.

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 ("Read full thread context and replies") and clarifies the scope as a full thread rather than a single message. It implicitly distinguishes itself from write siblings like relay_reply and relay_post, but never names an alternative tool, so the differentiation from relay_catch_up in particular is left to inference.

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 gives pagination guidance ("Use next_reply_cursor when has_more is true"), which is genuinely actionable, but it provides no when-to-use versus when-not-to-use guidance relative to siblings like relay_catch_up or relay_read equivalents. Usage is implied rather than stated.

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?

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real value beyond them: 'Does not overwrite earlier context' clarifies append-vs-replace semantics, and 'Retry-safe; returns the reply ID' states the retry contract and the return payload for a tool with no output schema.

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?

Three short clauses, front-loaded with the action, then the append guarantee, then the retry/return facts. No filler, no restating of the tool name.

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 mutation tool with no output schema and full schema coverage, the description supplies the two things structured fields cannot: non-destructive append behavior and the retry/idempotency contract. Only mild gap is the absent guidance on thread ownership or claiming work, which is partly covered by the session_id schema text.

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 100%, so all five parameters (including idempotency_key dedupe behavior and session_id's claiming caveat) are already documented in the schema. The description adds no parameter-level detail, which is the expected baseline 3.

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 ('Append a reply to a thread'), which is precise enough to separate it from relay_post (new thread) and relay_read_thread. It does not explicitly name a sibling, so it stops short of the 5 bar.

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 implies when this is used (adding to an existing thread) but never states when to prefer relay_reply over relay_post or relay_update, nor any preconditions such as needing a thread_id. Usage is inferable from the name and first clause only.

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?

Annotations already declare destructive, idempotent and open-world traits, so the bar is lower. The description adds real value beyond them: the optimistic-concurrency protocol, the current_version field on conflict, release semantics on done/open, and the lease_token precondition. It does not state auth requirements or whether a replaced summary is recoverable.

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?

Five short imperative sentences, front-loaded with the operation and concurrency model, and every sentence adds an actionable fact. No filler or restatement of the tool name.

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 destructive, idempotent mutation with no output schema, the description covers the concurrency contract, conflict handling, claim/lease preconditions, and retry guidance. What remains thin is the interaction with siblings (post vs reply vs update) and any permission requirements.

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 coverage is 75%, so most parameters are self-documented, and the baseline would be 3. The description adds context the schema doesn't: lease_token is required only while a claim is active, expected_version is used for optimistic concurrency, and a conflict surfaces current_version for rereading.

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 set (change status, replace summary) on a specific resource (thread) and names the concurrency mechanism. An agent can identify the operation clearly, though it never explicitly distinguishes this from relay_post/relay_reply for the 'change status' aspect.

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?

Gives concrete operating conditions: read latest version first, lease_token required under an active claim, done/open releases the claim, and how to react to a version conflict. It stops short of naming which sibling to use for posting replies or claiming, 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.