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

Annotations declare openWorldHint=true and non-destructive/non-idempotent, but they do not convey that this is a blocking, wait-for-reply operation; the phrase 'only when the next step depends on its reply' supplies that behavioral trait. The schema carries the timeout/error contract, so the remaining gap (reply shape, failure modes) is minor.

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 sentences, zero filler, with the core purpose front-loaded and the alternative routing in the second sentence. Nothing wastes the agent's attention.

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 moderate-complexity cross-session request tool with no output schema, the description covers purpose and routing well and the schema covers the timeout contract. It stops short of describing what a reply contains or how a timeout surfaces to the caller, which would have made it fully self-sufficient.

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 only 40%, so the description is expected to compensate, yet it mentions no parameters at all. The required 'to' and 'message' fields and the 'attachments' array are documented nowhere, leaving half the surface undefined.

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 ('Ask another intercom session a question') and immediately contrasts itself with the sibling intercom_send, so the agent can tell the two apart without opening either schema. The request/response nature of the call is unambiguous.

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 an explicit selection condition ('only when the next step depends on its reply') and names the alternative (intercom_send) along with the cases it covers (assignments, progress/status checkpoints, notifications). This is exactly the when-to-use / when-not-to-use routing an agent needs.

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 cover the safety profile (write, open-world, non-idempotent, non-destructive), and the description adds genuinely new context: a consent prerequisite and the key behavioral trait that 'Membership is additive' rather than replacing. It does not describe error behavior or what join does when the team is absent.

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, front-loaded with the approval precondition and the create/join/list modes. No filler; every clause carries an instruction or constraint.

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 four-parameter mutation tool with no output schema, the description covers modes, prerequisites, and the additive-membership semantics. Remaining gaps (return shape for the list mode, failure behavior) are minor.

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%, so the schema already documents all four parameters including the manager-only constraint on members and the create/name dependency. The description largely restates this ('members lets the manager add connected peers', 'Omit name to list teams'), so it adds little beyond the baseline.

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 specific verbs and resource: 'create or join a task team', plus a third mode ('Omit name to list teams'). This is clear, though it does not explicitly differentiate itself from the sibling intercom_team, which plausibly overlaps.

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 a precondition ('After user approval') and a mode-switch rule ('Omit name to list teams'), plus who may pass members ('the manager'). No explicit alternatives are named against the sibling tools, so it stops short of a 5.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scopng context—'intercom-connected Pi or Codex sessions' and 'on this machine'—but does not disclose return format, ordering, filtering, or other runtime behavior. No contradiction with the annotations is present.

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 a single focused sentence with no filler. The verb 'List' and the key resource and location qualifiers are front-loaded, making the core purpose immediately clear.

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 simple read-only list tool, the description is usable and the annotations provide the safety context. However, the two optional parameters are not semantically explained, no output schema exists to clarify return values, and there is no guidance distinguishing this from status/pending siblings, so the description is not fully self-sufficient.

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 for missing parameter meaning. The phrase 'on this machine' weakly aligns with the default scope=machine, but the description does not explain the directory/repo scope values or the meaning of include_self at all.

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 uses a specific verb 'List' with a clear resource: 'intercom-connected Pi or Codex sessions' on 'this machine'. This differentiates it from siblings like intercom_reply, intercom_send, and intercom_ask, which are communication actions, and from intercom_status/intercom_whoami, which query status or identity rather than enumerate sessions.

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 the tool should be used when an agent needs to enumerate local intercom sessions, but it does not explicitly state when to prefer this tool over siblings such as intercom_status or intercom_pending. There are no clear exclusions or alternative routing clues beyond the verb and resource.

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 openWorld, idempotent and destructive behavior; the description adds genuinely new context beyond them, namely the waiting semantics, that the wait does not end the Codex turn, and that plain MCP cannot wake an idle turn. It does not, however, explain that mark_read permanently clears unread state, which is the likely source of the destructiveHint.

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?

Purpose is front-loaded in the first sentence, followed by increasingly specific usage notes; four sentences carry distinct information. Slightly jargon-heavy (Codex turn, coi) but every sentence earns its place.

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 two-parameter read-with-wait tool and no output schema, the description covers purpose and the waiting workflow well but omits the shape of what is returned (messages vs. asks, counts) and the mutating effect of mark_read. Adequate but with clear gaps given no output schema to lean on.

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 50%: wait_ms is documented in the schema, mark_read is not. The description adds usage intent (wait_ms: 60000 to wait for incoming completion reports, mark_read: true alongside it) but never states what mark_read actually does as a side effect, leaving the undocumented parameter only partially compensated.

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?

Clear specific verb+resource: "Read unread inbound messages and unresolved asks" tells the agent exactly what the tool returns (pending inbox items). It does not, however, differentiate itself from siblings like intercom_list or intercom_status, so an agent must infer why 'pending' is distinct.

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 explicit situational guidance: use wait_ms: 60000 and mark_read: true when awaiting delegated results, and repeat after a timeout while results are still required. It also names an alternative mechanism (coi for automatic wake-on-message), though it does not mention sibling tools as alternatives or state when not to use 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?

Annotations already declare the safety profile (readOnly=false, destructive=true, idempotent=false, openWorld=true). The description adds behavior the annotations can't convey: the reply inherits the original team and that team cannot be overridden, which is a meaningful constraint on how the call should be formed.

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 sentences, zero waste. The action and its object are front-loaded, and the inheritance constraint follows immediately, so an agent gets purpose and key rule in one pass.

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, non-idempotent write tool with no output schema and no annotations on team, the description covers purpose, selector sourcing, and the team constraint well. It leaves some behavioral detail unstated (e.g., what a 'destructive' reply actually changes, or response/pagination behavior), but nothing critical for correct invocation 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 83%, so the schema baseline carries most parameters (to, which). The description still adds value: it ties askId/contextId to their source in intercom_pending and reinforces the team parameter's immutable-inheritance semantics beyond the schema's terse 'omit to inherit'.

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 (Reply) plus its target (an inbound ask or ordinary message) and identifies the exact selectors to use (askId/contextId from intercom_pending). This scope — responding to an existing inbound thread — is clearly distinct from the create-new-message siblings like intercom_send or intercom_ask without having to open a 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 clear context for use and, crucially, tells the agent where the askId/contextId values come from (intercom_pending), which is a real precondition. It does not name an alternative tool or state when NOT to use this (e.g., for starting a fresh thread), so it stops short of explicit routing.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds one genuinely useful trait beyond the annotations - 'non-blocking' delivery - but says nothing about delivery failure handling, retry semantics (relevant given idempotentHint=false), or whether attachments are persisted.

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 front-loaded sentence with zero filler; the core action leads and the addressing detail follows. Nothing is redundant with the schema or annotations.

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 non-idempotent mutation tool with no output schema and 25% parameter coverage, the description is thin: no delivery/error semantics, no guidance on attachment usage, no note on required permissions or what a failed send looks like. It leaves real gaps an agent would need filled before invoking confidently.

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 only 25%, so the description must compensate. It does explain the 'to' parameter's accepted forms (name, full ID, unique ID prefix), which the bare schema does not, but it adds nothing for 'message' or 'attachments' beyond what the nested schema shows. Partial compensation only.

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 (send) and resource (direct message to another intercom session) plus the addressing modes (name, full ID, unique ID prefix). It is clear what the tool does, but it never distinguishes itself from close siblings like intercom_reply or intercom_ask, which an agent must choose between.

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?

Usage is only implied: an agent can infer you call this to message a peer session, but there is no explicit when-to-use, when-not, or named alternative (e.g. versus intercom_reply for threaded responses). The addressing-format sentence hints at how to target recipients but not when this tool is the right choice.

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=false, destructiveHint=true, and idempotentHint=true, covering the mutation and repeat-call behavior. The description adds the transparency that the summary is published for other sessions to discover, which is useful beyond the schema. It does not contradict annotations.

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?

One concise sentence with all necessary information: the action, object, and purpose. No filler or redundancy. Front-loaded with the key verb 'Publish' and the resource.

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: one required parameter, no output schema, no nested objects. The description plus annotations provide enough to call it correctly. It states what to put in the summary, why, and the mutating behavior is captured by annotations. Minor omission: it doesn't explicitly say that calling it again overwrites the previous summary, though that's implied by idempotentHint and the nature of a status setter.

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 0%, so the description must compensate for the 'summary' parameter. It specifies that the summary should be 'short' and should describe what this Codex session is doing, giving meaningful content guidance. However, it does not clarify format, tone, or whether the summary replaces a previous one. For a single param, this is adequate but not thorough.

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 uses the verb 'Publish' with the resource 'short status summary' and specifies the audience and purpose: helping other sessions discover what this Codex session is doing. This clearly differentiates from sibling tools like intercom_reply or intercom_send, which focus on interactive communication, and from intercom_status, which likely retrieves status rather than setting it. It lacks an explicit contrast with siblings but the purpose is evident.

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 the usage: use it when you want other sessions to discover what this session is currently working on. That is a contextual signal, but there is no explicit when-to-use versus alternatives or exclusions. It does not mention that intercom_status could be an alternative for status retrieval, so the guidance remains implicit.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the specific status elements returned, which is useful but does not add behavioral traits beyond the annotations. No contradiction exists.

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 one short sentence, front-loaded with the main purpose and followed by a clear list of included items. Every word contributes information; there is no redundancy or filler.

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, read-only status tool with safety annotations already provided, the description is nearly complete. It names all reported categories. However, it leaves minor ambiguity about how 'pending asks' relates to the sibling intercom_pending tool, which could be clarified without much extra 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?

The input schema has zero parameters, and schema description coverage is 100% (vacuously). With no parameters to describe, the description's silence is appropriate. Baseline for 0-param tools is 4, and nothing is lacking.

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 uses a specific verb and resource ('Show intercom connection status') and enumerates concrete contents: connection status, active sessions, unread messages, and pending asks. It clearly distinguishes itself from action-oriented siblings like send/reply/ask, though it does not explicitly differentiate from intercom_pending, which may overlap on 'pending asks'.

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?

No guidance is given on when to use this tool versus alternatives. The sibling list includes intercom_pending and intercom_list, which could serve similar informational purposes, but the description never mentions them or gives selection criteria. The usage context is entirely 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds a fallback behavior ('managed-team discovery'), which is legitimate context beyond annotations, but it is vague and unexplained.

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 sentences with the list/inspect distinction front-loaded. Efficient, though the trailing fallback clause is opaque and adds little clarity per word.

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 and safety already covered by annotations, the description is serviceable but leaves the fallback mechanism and the format of returned team data unexplained. An agent can call it, but cannot predict the response shape or the fallback's implications.

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 schema gives no meaning for 'team' beyond 'string'. The description partially compensates by saying inspection is 'by name', implying the parameter is a team name rather than an ID, but it remains thin for a low-coverage parameter.

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 (Show/inspect) and resource (named task teams), and covers both modes: listing all teams or inspecting one by name. It does not distinguish itself from siblings like intercom_list or intercom_whoami, so it stops 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?

The two modes imply usage – omit the parameter to list, supply a name to inspect – but this is left to inference rather than stated. No alternatives among the sibling tools are named, and 'Falls back to managed-team discovery' describes behavior rather than when to use the tool.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the returned identity is meant for targeting, but it does not disclose the return format or any further behavioral details.

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?

One sentence with no wasted words. The key information is front-loaded: what the tool returns and why it is useful.

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 no-parameter, read-only identity lookup, the description is sufficient. It clearly tells the agent what the tool produces and why that output matters, and no additional invocation guidance is needed.

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 has zero parameters and 100% schema coverage, so the parameter semantics burden is minimal. The baseline for a zero-parameter tool is 4, and the description does not need to explain parameter behavior.

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 ('Return'), a specific resource ('this Codex session's intercom identity'), and a clear purpose ('for reliable targeting'). This distinguishes it from the sibling intercom tools, which handle other actions like sending, replying, or listing.

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 phrase 'for reliable targeting' gives clear context for when to call this tool: before actions that need to address the current session. However, it does not explicitly name alternatives or state when not to use it.

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