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

Annotations only declare write/non-destructive/non-openWorld; the description adds real behavioral context: idempotent retry via recordId and a persistent 'labeled reported' provenance marker on all content. It omits error/failure behavior and whether records can be amended or removed later, which matters for an append-style mutation.

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?

Four short sentences, front-loaded with purpose before constraints, and every clause carries information (scope, idempotency, privacy, labeling). Slightly dense but no 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?

Covers purpose, idempotency, and privacy boundaries adequately for a write tool with no output schema. Given 8 parameters at 0% schema coverage with mandatory fields like evidence, the description is not complete enough to guarantee a correct first 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% and 7 of 8 parameters are required, yet the description only touches recordId (idempotency). Mandatory fields like evidence, nodeKind/nodeId, boardId, role, and observedAt are completely unexplained, leaving the agent to guess at required semantics.

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 ... work record') and sharply delimits it from a native transcript. However, with siblings like team_record_workflow and team_record_execution present, it never explains how an agent-reported record differs from those sibling recording tools, so differentiation is only partial.

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 exclusionary guidance ('not a native transcript', don't collect hidden reasoning, credentials, private session files), which is useful. But it never names an alternative tool or states positive conditions for choosing this over team_record_workflow / team_import_thread_page among 15 siblings, so the routing 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?

The description adds substantial behavioral context beyond the annotations: the operation is reversible, does not delete tasks, member records, transcripts or project files, and does not stop agents. This directly addresses the effects an agent needs to understand before invoking a non-readonly mutation.

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 action and confirmation condition front-loaded. Every clause adds useful information about reversibility or non-effects, and there is no 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?

The description does well on safety and reversibility, which is important for this mutation tool. However, with 0% schema description coverage and no output schema, it leaves key invocation details missing, particularly expectedRevision semantics and what confirmation must cover.

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 carry parameter meaning. It only indirectly covers action (archive/restore) and confirmed (explicit user confirmation), while boardId and especially expectedRevision are left unexplained, including what revision semantics or mismatch behavior apply.

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: archive or restore a workbench. This is clear enough to distinguish the tool's core action, but it does not explicitly differentiate it from any sibling tool or resolve the board/workbench terminology.

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 a clear usage condition: action should occur after explicit user confirmation of scope. It does not state when to choose archive versus restore, nor when not to use this tool, so it stops short of full alternative 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?

Annotations already state readOnlyHint=false and destructiveHint=false, and the description correctly matches that by describing a registration (write) operation with no destruction. It adds real behavioral context beyond annotations: it discloses that host history is not read, that parent/UUID guessing is forbidden, and that missing/ambiguous/unavailable sources are recorded as visible resolution states rather than failing silently.

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 four tight sentences with the core purpose front-loaded and no filler. Some clauses ('Returns nextRead only after unique mapping') are dense and would benefit from a slightly clearer phrasing, but every sentence carries 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?

For a complex 8-parameter mutation with no output schema and no schema descriptions, the description covers purpose, exactness constraints, and failure-state behavior. It still leaves required parameter meaning and the nature of 'nextRead' unexplained, so it is only partially complete for the tool's complexity.

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% across 8 parameters, so the description carries the full explanatory burden, and it only partially does so. It conceptually maps the 'subAgentActivity path/UUID items' and the parent-source fields, and 'unavailable sources' hints at unavailableReason, but boardId, memberId, and the required expectedRuntimeRef are never explained, leaving required inputs ambiguous.

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: 'Resolve and register one recorded child' using 'exact subAgentActivity path/UUID items' from its spawning parent. An agent can tell it is a per-child binding/registration operation rather than a listing or snapshot, although it never names a sibling such as team_bind_session to disambiguate.

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?

Guidance is implied through constraints ('Does not read host history itself', 'Never substitutes another parent or guesses a UUID'), which tells the agent the caller must supply exact relayed data. However, there is no explicit when-to-use / when-not-to-use statement and no reference to the alternatives among the many sibling tools.

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 only declare the mutation/readOnly flags, while the description adds substantial behavioral context: old members, executions and snapshots keep their original source and cannot be synced under a new origin, and the user-facing confirmation protocol. This is exactly the extra consequence disclosure annotations cannot provide.

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 the core action, then the rebind prerequisites, then consequences, then the safety caveat. Dense but every sentence carries information; no 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 7-parameter mutation tool with no output schema and 0% schema coverage, the description covers the safety protocol and history isolation well, but leaves expectedRevision (likely a concurrency guard) and nativeIdSource unexplained, so an agent still lacks guidance on those inputs.

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 carry parameter meaning, and it does explain sessionId (full native UUID), previousSessionId (exact match), confirmRebind and evidence. However, nativeIdSource (which has an enum) and expectedRevision are left unexplained, so compensation is partial.

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 pair (bind or explicitly change) against a concrete resource (a board conversation), and scopes it to a full native UUID. It does not name a sibling alternative, but the action is unambiguous enough that an agent can distinguish it from record-append or board-creation siblings.

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 a clear triggering condition for the change path (a rebind requires exact previousSessionId, confirmRebind=true, and evidence after showing old/new IDs and history isolation to the user). It does not explicitly compare to siblings or say when not to use it, keeping it below 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=false, destructiveHint=false, and openWorldHint=false, so safety and locality are largely covered. The description adds useful context: the board is created 'empty' and 'local', and no agent or thread is spawned as a side effect. It doesn't cover permissions, failure modes, or return value, so a 3 is appropriate.

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, the affirmative purpose front-loaded and the scope exclusion second. Zero waste and no 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 single-parameter create tool with annotations covering the safety profile, the definition is close to sufficient. Missing pieces are minor but real: where the board persists, what the response contains, and whether a title must be unique — none of which the annotations or schema address.

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?

Only one parameter ('title') with 0% schema description coverage, but the name is self-explanatory and the schema supplies minLength/maxLength constraints. The description adds nothing about the parameter, so it neither compensates nor creates ambiguity — 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 ('Create an empty local team board') and immediately narrows scope with 'Does not create any agent or thread,' which heads off confusion with siblings like team_bind_session or team_bind_agent_activity. It doesn't name an alternative sibling explicitly, 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 explicit when-to-use guidance, no prerequisites, and no named alternative among the many team_* siblings. The negation about agents/threads is a scope boundary, not usage guidance, so an agent still has to infer 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 non-read-only, non-destructive, closed-world, so the description correctly adds state semantics instead: the task is created 'pending' and 'unassigned', and creation has no dispatch side effect. It omits anything about what the call returns or whether duplicates are rejected.

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, the creation semantics front-loaded and the dispatch caveat immediately after. No filler, nothing repeated from 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 and a mutation tool, the safety profile is covered by annotations and the pending/unassigned state is covered by the description, but the blockedBy reference format and return value (e.g. new task ID) remain unaddressed. Adequate, not 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%, so the description must carry the parameter burden, yet it only gestures at 'optional dependencies' without mapping it to blockedBy (task IDs? titles?) or explaining boardId or description. An agent must guess at the blocking-reference format.

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 ('Create an ... pending task') and adds the qualifier 'unassigned', which separates it from team_update_task and assignment-oriented siblings. It does not name a sibling explicitly, 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 sentence 'Task assignment alone does not dispatch work to any agent' implies that dispatching requires a different tool (likely team_request_execution), but the description never names it or states the condition for using it. Usage is implied rather than prescribed.

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 only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description carries real weight: it discloses that no model is started and no host API is called, that reasoning and credentials are never imported, and that snapshots stay marked agent-relayed and possibly truncated. This is genuine context beyond the annotations and is consistent with them (a non-destructive write).

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?

Dense but every sentence adds a distinct constraint (no model, no host call, exact threadId, excluded content, snapshot marking). Front-loaded enough, though the telegraphic style is harder to parse than plain prose.

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?

Behavior is well covered for a complex, multi-parameter tool with no output schema, but with 10 params at 0% coverage and no explanation of the cursor/nextCursor paging contract or evidence/readAt fields, an agent cannot confidently populate the input.

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 10 parameters. The description only maps loosely to content types (messages/status/tool summaries) and threadId binding; boardId, memberId, recordId, readAt, evidence, cursor, nextCursor, and hostId remain entirely 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?

States a specific verb (relay/import) and resource (a bounded page actually returned by the read_thread host tool), scoping it to an explicitly bound member. It distinguishes itself from a full snapshot by stressing this is a page, not a complete transcript, though it doesn't name a sibling tool directly.

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?

Implies the workflow (must be a page already returned by codex-app-tools.read_thread, exact threadId binding required) but never says when to prefer this over team_snapshot or team_read_records, nor when not to use it. Usage is inferable 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?

Beyond annotations, the description discloses important behavioral traits: evidence and observation time are lead-relayed and not server-authenticated, stale observations cannot overwrite newer ones, and resumeAvailable has a narrow truth condition. It does not cover permission requirements or error behavior, but the key trust and concurrency semantics are stated.

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 three front-loaded sentences with no filler; purpose comes first, followed by trust/concurrency constraints and the resumeAvailable condition. It is dense with domain jargon but appropriately sized for a complex mutation 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?

For a 10-parameter mutation tool with no output schema and 0% schema description coverage, the description covers critical trust and staleness behavior but does not fully specify all required parameters or the response side. It is adequate but leaves notable gaps an agent would need to infer.

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 carry parameter meaning. It adds useful semantics for evidence, observedAt, resumeAvailable, and indirectly expectedRevision via the stale-overwrite rule, but it leaves boardId, memberId, runtimeRef, sourceThreadId, and the state enum values 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 action and resource: recording an actual collaboration list_agents or wait_agent state for an exact recorded runtime path. It is clear enough to distinguish from generic record/report tools, but it does not explicitly contrast itself with siblings like team_record_execution or team_report_member.

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 by the mention of list_agents or wait_agent observations; there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The agent must infer the appropriate context from the source enum and the word 'actual'.

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=false, openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses a session-memory side effect and clarifies the correlation is not a native Codex thread ID, but it never says what "open" operationally does or returns.

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, which is good. The middle sentence is dense and hard to parse ("remember that selection if the host supplies anonymous session metadata"), and the thread-ID disclaimer arrives without setup.

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 a mutation-flagged tool, the description should say more about what opening produces and how the panel state relates to boards created by team_create_board. It covers the identity caveat but leaves the operational result unexplained.

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 carry the parameter, and it does explain boardId's semantics (remember the selection) plus the empty-object reopen case. However it never says where a boardId comes from or its format, and the "anonymous session metadata" phrasing is vague.

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: "Open the persistent shared task board and team map." An agent understands what the tool does, but there is no differentiation from siblings such as team_snapshot or team_create_board, and "team map" is never explained.

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 call this versus team_snapshot, team_create_board, or team_bind_session. The only routing help is the negative "Does not discover or control agents," which excludes one use case but does not positively guide selection.

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, openWorldHint=false and destructiveHint=false, so safety is covered. The description does add one real behavioral caveat — results are stored bounded snapshots rather than live native data — which affects how much the agent should trust freshness. That caveat is phrased abstractly ('complete-native access is explicitly distinguished from...') and omits pagination behavior, ordering, or result size, so it is useful but thin.

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 main capability is front-loaded in the first sentence, which is good. But the third sentence largely restates the second in more abstract language ('explicitly distinguished from stored bounded snapshots') without adding actionable detail, so the payload is diluted by a near-redundant clause.

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, 0% parameter documentation, and five inputs including a cursor-like 'after', the description should explain what a page of records looks like and how to page through them. It covers neither, so an agent can identify the tool but not reliably drive its pagination or interpret its node/board identifiers.

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 five parameters, so the description must carry the burden and it does not: boardId, nodeId, nodeKind (the enum member/workflow choice), and especially 'after' (cursor id? offset?) and 'limit' are never mentioned. Only 'for one node' vaguely gestures at nodeId/nodeKind, leaving the agent to guess the pagination contract.

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 ('Page') plus an enumerated set of resources ('recorded work observations, relayed public-host snapshots and execution receipts') scoped to one node, which lets an agent distinguish this read tool from the record/append siblings. The jargon ('public-host snapshots', 'execution receipts', 'node') is never defined, so the resource identity is clear in shape but fuzzy in substance.

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?

'Does not directly read native threads or private host sessions/databases' gives an explicit when-not boundary covering the most likely misuse. However, it names no alternative tool among the many siblings (team_panel, team_import_thread_page, team_snapshot), so the agent must still infer where to go for native thread access.

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?

Goes meaningfully beyond the annotations by disclosing that these are self-reported observations rather than authenticated runtime telemetry, which tells the agent the data is untrusted. It also flags the integrity rule (never fabricate runtimeRef/success) and a state-transition ordering constraint for confirm. What it omits is failure/concurrency behavior, e.g. what happens when expectedRevision is stale.

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 purpose before the caveats, with essentially no filler. Slight loss because the action-precondition sentence is compressed to the point of ambiguity about which action it constrains.

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 13-parameter, 5-required mutation tool with no output schema and zero schema documentation, the description leaves most of the calling contract unstated: no per-action parameter requirements, no revision/optimistic-concurrency semantics, and no notion of what a successful record returns.

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 13 parameters, so the description carries the whole burden and largely does not: it mentions only runtimeRef and the confirm action. Terms like expectedRevision, evidence, nativeIdSource, artifacts, hostId, and spawnCallId are never explained, and there is no indication of which fields are required per action.

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?

"Record a real lead spawn receipt, worker start/result, or parent-collected result" gives a concrete verb plus the resource types it covers, and the action enum reinforces the scope. It is distinguishable from siblings like team_record_workflow or team_report_member by its focus on execution lifecycle receipts, though it never names those siblings 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?

"confirm completes the task only after worker report and collection" is a real precondition for one action, and "Never invent runtimeRef or success" sets a usage constraint. But there is no guidance on when to pick this tool over team_report_member, team_request_execution, or team_record_workflow, and no mapping of which action to use at which lifecycle stage.

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 establish it as a non-read, non-destructive, closed-world write; the description adds genuinely new behavioral context: it creates only a visual grouping, does not start work, does not alter real parent relationships, and uses revision-based optimistic concurrency via expectedRevision. It stops short of saying what happens on a revision mismatch or whether re-recording is idempotent.

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 core action and immediately followed by the most likely misconception. No filler, though the compressed phrasing 'workflow/run group' costs a little clarity for a marginal gain in brevity.

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 7-required-parameter mutation with no output schema and no schema descriptions, the description is too thin: an agent cannot construct a valid call without guessing the meaning of most fields or the expected evidence format. Annotations cover the safety profile, but parameter and outcome semantics remain largely absent.

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 7 required parameters, so the description carries the full burden. It explains only expectedRevision (use 0 for new groups); boardId, workflowId, title, parentMemberId, status, and evidence are left entirely unexplained, including what 'evidence' should contain and what parentMemberId references.

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 ('Record an actual caller-owned workflow/run group') and clarifies the semantic scope: it visually groups agents and does not replace parent relationships or start work. That distinguishes it in spirit from siblings like team_record_execution and team_report_member, though no sibling is named.

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?

One concrete usage rule is given ('Use expectedRevision=0 for a new group'), and negative guidance rules out treating this as a real parent link or a work trigger. However, there is no explicit guidance on when to choose this over team_report_member, team_record_execution, or team_append_record, which is the main routing ambiguity.

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=false, openWorldHint=false, so the mutation profile is covered. The description adds genuinely non-obvious context not in annotations: the record is explicitly marked as 'reported' (i.e., unverified) and that actor IDs are conventions rather than authenticated identities, a meaningful trust caveat for a write tool. It remains silent on repeat-call behavior (duplicate vs. upsert on memberId), what happens to prior state for the same member, and failure modes — gaps that matter for a 14-parameter write.

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 action and its labeling, followed by the disambiguation clause. No filler. The negative list is dense but each item rules out a plausible misreading 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?

A 14-parameter, 14-required-by-4 write tool with zero schema descriptions and no output schema demands more than three sentences. Nothing tells the agent which optional fields (evidence, tokenTotal, durationMs, spawnCallId) to supply or when, nor what a successful call returns or how to recover from rejection. The trust caveat is good but the operational picture is incomplete.

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 14 parameters, so the description must carry the explanatory load and does not. Only a glancing nod exists ("actor IDs are conventions"), with no explanation of what memberId, hostId, nativeIdSource, runtimeRef, or evidence mean or how required fields interact. An agent cannot determine from prose what distinguished a valid report from a malformed one.

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 ("Record a caller-reported member and state") plus a storage qualifier (labeled reported). The explicit "Does not create, verify, resume, or control a native agent" separates it from agent-control siblings like team_bind_agent_activity or team_request_execution. It stops short of naming which sibling to prefer for native-agent lifecycle work, but an agent can tell this is a bookkeeping write, not a control call.

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 a negative usage boundary — this is not for creating, verifying, resuming, or controlling a native agent — which is useful exclusion guidance. However, it never states the positive condition for choosing this tool (e.g., when to file a report versus calling team_bind_agent_activity or team_snapshot), nor any prerequisite such as an existing board. Usage is implied rather than prescribed.

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 a non-destructive write in a closed world; the description adds a genuinely non-obvious behavioral fact, that no agent is started and the lead must act through real host tools. It stops short of saying what this call actually mutates (a queued request record?) or whether the call blocks, which matters given readOnlyHint=false.

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 dense sentences, front-loaded with the action and immediately followed by the constraint that most affects agent behavior. No filler, no 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?

For a six-parameter mutation tool with zero schema descriptions and no output schema, the description carries far too little: no parameter meaning, no concurrency semantics for expectedTaskRevision, no description of what is returned or how the recorded reference flows back.

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% and the description mentions none of the six parameters. Critically, expectedTaskRevision clearly encodes an optimistic-concurrency precondition, and instructions vs. workflowId vs. parentMemberId are entirely undefined in either the schema or the description.

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 object ("request native execution") and names the actor that fulfills it ("through the lead"). It also carves out the key negative ("starts no agent"), which tells an agent this is not an agent-spawning call. The phrase "native execution" is unexplained jargon, and no sibling (e.g. team_record_execution) is named to sharpen the boundary.

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 applies (when the lead, not the tool, must perform host collaboration) and prescribes a follow-up action (record the returned reference). But it never contrasts this with team_record_execution or team_bind_agent_activity, so the choice between 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds content scope and a limitation, but does not disclose auth needs, pagination, or other behavioral details; no contradiction 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?

Two sentences, front-loaded with the action and scope. The final sentence is terse but not wasteful, and the overall size is appropriate for a simple read-only 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?

For a simple read-only tool with annotations and no output schema, the description covers the high-level return content. It still leaves boardId semantics and sibling selection unclear, so it is only adequately 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?

The sole parameter boardId has 0% schema description coverage. The description implies that omitting it lists boards and providing it reads one board, but never names boardId or explains its format, constraints, or expected value, so it only partially compensates.

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: list boards or read one board, and names included data such as task revisions and member observations. It does not differentiate this tool from siblings like team_panel or team_read_records, 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?

It implies that omitting boardId lists boards and providing it reads one board, but gives no explicit when-to-use, when-not, or alternatives among the many team_* siblings. The phrase 'No native agent discovery' is an exclusion but too cryptic to guide tool selection.

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?

The description adds vital operational behavior not found in annotations, specifically stating that the call must 'Refresh after STALE_REVISION.' This is essential for robust function execution.

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 definition is extremely dense and efficient, packing operational constraints, parameter semantics, and the full list of capabilities into a single, cohesive sentence without any wasted words.

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 the high number of parameters and the lack of any output schema, the description covers essential behavioral context (revision handling, role definition) and the full scope of the tool's functionality (supported actions).

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?

With 0% schema description coverage, the description provides high-value semantics for the 'actorId' parameter, clarifying that it refers to a workflow role, not the host identity. While it lists the actions (which are in the enum), it does a reasonable job of clarifying key ambiguous parameters.

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 purpose is stated clearly as updating a shared task and is significantly enhanced by listing all supported 'actions' like claim, release, and reassign. This explicitly defines the scope of the tool.

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 guides usage by listing supported actions, which tells the agent when to use the tool for specific outcomes (e.g., 'reopen' vs 'complete'). It also provides critical constraints on parameter usage, such as the definition of 'actorId' as a workflow role.

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