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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is partly covered. The description usefully adds that acknowledgement is a delivery record only, not a reply or completion, but is silent on the destructive implication, whether re-acknowledging fails or is harmless, and on the 50-message batch limit.

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 tight sentences with the action first and the disambiguation second. Nothing is wasted and the most important constraint is front-loaded.

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 mutating tool flagged destructive with no output schema and zero parameter documentation, the definition does not say what state changes, what happens on duplicate acknowledgement, or how the batch of message IDs is scoped to an installation. It is clear about intent but thin on the details needed to call it correctly.

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 three parameters (installationId, messageIds, runId), yet the description mentions none of them. It gives no hint that messageIds is a 1-50 batch array or that installationId/runId are UUID scoping identifiers, so the schema alone must carry all parameter meaning.

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 gives a specific verb and resource ('Acknowledge messages') plus a precondition ('after consuming their context'), so the action is unambiguous. The clause 'never a reply or task completion' implicitly separates it from reply_agent_message and complete_task, though no sibling is named outright.

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?

'After consuming their context' implies the trigger condition, and the negative scoping steers away from replying or completing tasks. However, no alternative tool is named and there is no explicit when-not guidance (e.g., when to prefer reply_agent_message or get_agent_message first).

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 annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is known. The description adds useful context that the local socket path contains no credential, but it does not describe the returned configuration structure or any runtime constraints beyond that security note.

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 short and front-loads the return value before adding the credential note and setup steps. Every sentence contributes, though the setup instructions could be tighter or more explicitly framed as usage guidance.

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

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

With zero parameters, no output schema, and rich annotations, the description gives enough context to understand the tool's purpose and immediate follow-up actions. It could do slightly more to explain what the returned hook configuration contains, but the core information is present.

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

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

The tool takes zero parameters, so parameter semantics carry baseline credit. The description does not need to explain input arguments, and the empty schema is consistent with that.

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 ('Return') and resource ('shared Codex hook configuration for this installation'), so the agent can tell what the tool does. It does not explicitly distinguish this from sibling tools, but no sibling appears to offer hook configuration, making the purpose still clear.

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 post-retrieval instructions ('Merge hooks with existing config', 'enable TEAM_TIME_COORDINATION_ENABLED=1', 'review/trust the exact hooks'), which implies a setup/configuration use case. However, it does not state when to call this tool versus alternatives such as team_time_bootstrap or team_time_workflow.

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 readOnly/idempotent/non-destructive, so the bar is low; the description still adds real value by flagging that message text is untrusted task data (a prompt-injection warning) and that delivery is limited to undelivered messages. It says nothing about ordering, limits, or what an empty inbox looks like.

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 primary purpose, and each sentence carries distinct information (scope, follow-up routing, trust warning). Zero 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?

With no output schema, the description should hint at the returned message shape or at least the fields needed to act on a message, and it doesn't. The security warning and reply/ack routing are strong, but the unexplained optional runId and unstated return shape leave real gaps for a tool an agent will act on directly.

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 carries the full burden for two UUID parameters, yet it never mentions installationId or the optional runId. An agent must guess that runId scopes the inbox to a single run, which is exactly the kind of meaning the description should supply.

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 with scope: read undelivered task messages for an installation. It also explicitly separates itself from two siblings by naming reply_agent_message and declaring acknowledgment a distinct action, so an agent can route without opening other schemas.

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 clear context for the follow-up actions ('reply... using reply_agent_message; acknowledgment is separate from answering'), which steers the agent to the right sibling tools after reading. It does not, however, address when to use this inbox versus team_time_get_agent_message or team_time_pending_commands, which are the closest overlapping reads.

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 real context beyond the annotations: a 60-second server deadline, a non-blocking posture toward offline/idle chats, and the explicit caveat that a reply is data rather than authorization. However, annotations declare destructiveHint=true, and the description never explains what state it can destroy or why a mere question is flagged destructive — a meaningful gap.

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 the core action and the deadline immediately after. Dense but not wasteful; the 'use their checkpoint' clause is terse to the point of being cryptic, slightly hurting the structure.

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?

It conveys the deadline and the coordination semantics, which are the hardest things to infer, and there is no output schema to explain. But with destructiveHint=true, no parameter documentation, and unexplained references to 'checkpoint' and 'preserve claims', an agent still lacks enough to call this 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 0% across four required parameters (taskId, senderRunId, recipientRunId, body), and the description never explains any of them, including the 2000-char body limit or which run ID is which side of the exchange. The phrase 'task-linked chat' obliquely hints at taskId and recipient, but that is not adequate compensation.

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 names a specific verb and target — asking a task-linked active chat a coordination question — which is distinct from asynchronous siblings like leave_agent_message or reply_agent_message. It stops short of explicitly contrasting itself with those tools, so an agent must infer 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?

It gives a clear when-not rule (skip offline/idle chats and use their checkpoint instead) and a constraint on how to treat the answer (data, not permission to expand work). It does not name the alternative tool an agent should fall back to, so the routing guidance is incomplete.

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 establish that this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful behavioral context: it returns all permitted projects, notes that names can be ambiguous, and tells the agent to use returned IDs. It does not detail exact return fields, but it adds meaningful data-handling guidance beyond the 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?

Three short sentences, front-loaded with the bootstrap instruction and followed by only the two ID-handling notes an agent needs. There is no filler, and every sentence contributes.

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 bootstrap with no output schema, the description identifies the major returned resources and includes the most important ID-mapping caveat. It stops short of describing the exact shape of the returned context or nested member/project data, but the sibling tools provide detailed listing alternatives.

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?

This tool has zero parameters, so the baseline is 4. The description adds useful cross-tool ID guidance ('assigneeId is member.userId') even though there are no local parameters for it to document.

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 clearly identifies this as a bootstrap/composite read that returns context plus all permitted projects, members, workflow, and tags. It distinguishes itself from the sibling list_* tools by bundling those resources, though it does not use an explicit verb such as 'retrieves' or 'returns'.

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 'Start here' gives an explicit entry-point instruction, which is clear guidance for first-call sequencing. It does not name alternatives or explain when not to use this bootstrap, but the intended context is obvious.

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?

Adds substantial context beyond the annotations: optimistic concurrency ('a competing claim loses the version race'), refusal conditions, and the fact that this only records ownership without mutating status. That explains the destructiveHint/idempotentHint profile in practical terms. It doesn't cover authorization requirements or what the caller receives on a lost race, so not a 5.

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 tight sentences, each earning its place: scope, identity requirement, contention behavior, refusal rules, and sequencing advice. No restatement of the name 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 three-parameter mutation tool with no output schema, it covers the critical behavior (race semantics, refusals, ownership-only effect). The main omission is what a successful claim returns or how to recover from a version loss, which the agent would need before retrying.

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 must carry the load and it mostly does: expectedVersion is glossed as 'its observed version', agentId as the 'unique chat/run' identity, and taskId as the target task. It does not explain accepted formats or where the observed version is obtained (presumably team_time_get_task), leaving a small gap.

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 with explicit scope: 'Claim one existing not-started task using its observed version.' The not-started constraint and version-based ownership semantics separate it cleanly from release_claim and update/set_status 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?

Gives clear usage context ('agentId must identify this unique chat/run') and an implicit exclusion set ('Refuses existing claims and in-progress/completed work'), plus a sequencing rule ('change status separately before editing code'). It stops short of naming team_time_release_claim or the exact situation where the agent should not claim at all, so not a full 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds real context beyond them: an atomic side effect on the key creator's running timer, and the failure mode where other members' timers block completion. The one notable omission is any mention of the expectedVersion optimistic-concurrency check, despite the tool being non-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 action, then the parameter rule, then the side effect. Dense and mostly waste-free, though "Complete verified work" is slightly jargon-laden.

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 mutation with no output schema and 0% schema coverage, the description covers side effects and the claimId rule but leaves the mandatory expectedVersion semantics and the result payload shape unexplained. Adequate, but not enough to invoke confidently on the first try.

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 and it largely does not. It clarifies claimId's conditional role, but says nothing about expectedVersion (optimistic concurrency token) or taskId, and "test evidence and relevant links" do not map to any schema field — only `result` exists, so it is unclear where that content goes.

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+resource ("Complete ... work", i.e. a task) and adds scope: record outcome, test evidence, links. An agent can tell this is the completion action rather than a generic edit. However, it never names team_time_set_status or team_time_update_task and why completion is a distinct operation from setting status.

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?

"Include claimId for claimed work" is a genuine conditional rule that tells the agent when a parameter is required. Beyond that there is no when-to-use / when-not-to-use guidance, no prerequisites (e.g. must the task be claimed first?), and no differentiation from the sibling status/update 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 already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered structurally. The description adds no behavioral context beyond a list of fields — it doesn't say whether 'confirm' means a fetch or a validation that can fail/mismatch, nor what open-world access it performs.

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?

It is a single short sentence with no filler, but it is a bare fragment lacking a clear subject and reads more like a checklist than a front-loaded purpose statement. Brevity here comes at the cost of specification.

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

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

With no output schema, the description is the only place to explain what the 'context' actually returns and how it should be used (e.g., call before other team_time_* operations). It gestures at the fields but doesn't say the response shape, sequencing, or failure modes, leaving a zero-parameter context tool underspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description's field list reads as return-value content rather than parameters, which is a minor mismatch but harmless.

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 sentence names what is returned (organization, access target, identity, allowed operation IDs), which hints at a context/permissions lookup, but the verb 'Confirm' is ambiguous — it could mean validate, fetch, or assert. It does not differentiate from siblings like team_time_bootstrap or team_time_workflow, which plausibly overlap in scope.

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 tool, when not to, or which sibling to use instead. With 25+ team_time_* siblings including bootstrap and workflow, the agent has no basis to choose this one over them.

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 openWorldHint, non-idempotent, and destructive, so the safety profile is partly covered. The description adds genuinely non-obvious behavior: creation cannot atomically deduplicate competing agents, which warns the agent about race conditions. It still doesn't say what is returned or whether defaults are applied to statusId.

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, dense sentences with zero filler, and the precondition plus the concurrency caveat are front-loaded. 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?

For a 7-parameter mutation tool with no output schema, 0% schema coverage, and open-world/destructive annotations, the description covers the key concurrency risk but omits return value shape, default status behavior, and any permission requirements. Adequate but with clear gaps.

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, and it does partially: 'Tags are names; assigneeId is a userId' clarifies two ambiguous fields and bootstrap resolves IDs. However statusId, projectId, dueOn, and description formats/constraints are left entirely to the unlabeled schema, so half the parameters remain semantically opaque.

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 (create) and resource (unfinished work/task), and the name confirms it is a task-creation tool. It is distinguishable from siblings like team_time_update_task or team_time_complete_task by the 'unfinished work' framing, though the phrase 'work' rather than 'task' is slightly imprecise.

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 concrete precondition ('after checking for overlapping tasks') and routes ID resolution to team_time_bootstrap, which is real actionable guidance. It stops short of naming exclusion cases (e.g. use complete_task for already-done work, or update_task instead of recreating).

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, non-destructive, and openWorld behavior. The description adds meaningful behavioral context by clarifying that this tool reads state rather than the answer body and that a no-reply condition does not release another agent's task claim.

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

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

The description is short and front-loads the state-reading purpose before the inbox alternative and behavioral warning. Each sentence contributes something, though the first sentence is awkwardly phrased and could be clearer.

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 no output schema, the description gives only a high-level view of the returned state and does not describe the response shape or deadline semantics. It is minimally adequate but leaves important retrieval details 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?

The schema has 0% description coverage and only one required parameter, messageId. The description does not explain what messageId identifies, where to obtain it, or how it relates to the question/message being checked.

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 read operation on a question's response/deadline state, which gives some idea of the resource. However, it never clearly says it retrieves an agent message's state by messageId, and the wording is cryptic relative to the tool name and 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 explicitly routes the agent to the inbox for the answer body, distinguishing this state-check tool from team_time_agent_inbox. The warning about no reply not releasing another agent's task claim adds useful context, though it does not fully enumerate alternatives such as wait_agent_reply.

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 annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds a useful precondition about inspecting the claim before starting work, but it does not explain return behavior, error cases, or what 'version' means in practice.

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 two short sentences, front-loads the core operation, and contains no filler. Every sentence contributes either purpose or a workflow instruction.

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 tool with rich annotations, the description covers purpose and a claim-inspection precondition. However, it omits taskId semantics and, with no output schema, does not describe what reading the task and version 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% and the only parameter, taskId, is never mentioned in the description. Even though taskId is self-explanatory, the description does not compensate for the missing schema documentation or explain expected format/source.

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 ('Read') and resource ('task and version'), making the core operation clear. It does not explicitly distinguish itself from siblings like team_time_list_tasks, but the singular 'task' and 'version' scope helps differentiate it.

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 context: inspect the task description for a team-time-mcp claim before starting work. It does not name alternatives or when-not-to-use cases, but the primary when-to-use condition is explicit.

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 establish that this is a safe, read-only, idempotent operation. The description adds meaningful behavior: it lists the returned content categories, explains pagination via a cursor for older conversation, and notes that a task claim remains authoritative when another agent does not reply. The cursor name is inconsistent with the schema, but the behavioral disclosure itself is substantive.

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 sentences and front-loads the returned content list. The final sentence about claim authority is somewhat opaque but still relevant coordination context; overall it is tight and readable.

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 does well to enumerate the returned data categories and pagination behavior. However, it leaves the required taskId unexplained, uses a cursor name that does not match the schema, and gives no routing guidance relative to sibling read tools.

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 explain taskId and beforeId. It does neither: taskId is never described, and the only cursor guidance references 'nextBeforeId', which is not a declared parameter (the schema uses 'beforeId'). This mismatch reduces clarity rather than compensating for the schema gap.

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 clear verb ('Read') and enumerates the linked resources: chats, availability, declared files, checkpoints, and recent task messages. It is understandable as a task-scoped read tool, though it does not explicitly distinguish itself from siblings like team_time_get_task or team_time_agent_inbox.

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 implied by the listed content and the cursor instruction for older conversation, but there is no explicit guidance on when to choose this tool over team_time_get_task, team_time_agent_inbox, or team_time_get_agent_message. No exclusions or alternatives are named.

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 flag destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds genuinely non-redundant delivery semantics: the note is 'durable', it reaches chats that are idle or offline, and it will not block awaiting a response. It does not warn that repeat sends create duplicate notes (consistent with idempotentHint=false but unstated).

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, no filler, with the core behaviour front-loaded and the negative constraint appended as a qualifier. Every clause 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?

There is no output schema, so the description should at least say what a successful send yields (message ID? nothing?) and whether delivery is guaranteed — it says neither. For a non-idempotent, open-world mutation with four undocumented parameters, the definition is adequate to recognize the tool but thin for calling it correctly.

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 four required parameters, so the description carries the full burden and mostly fails: 'task-scoped' hints at taskId, but senderRunId versus recipientRunId — the most error-prone distinction, since the agent must supply its own run ID — is never explained. Nothing is said about the 2000-character body limit or the UUID/pattern constraints.

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 ('leave a durable task-scoped note') plus the delivery target ('linked chat, including an idle/offline chat'), which is far more concrete than a tautology. It implicitly separates itself from interactive siblings by declaring it does not start a turn, though it never names ask_agent or wait_agent_reply 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?

'Does not start a turn or wait for a reply' functions as an explicit when-not clause, and 'including an idle/offline chat' gives the condition that favours this tool over a live exchange. What is missing is a named alternative ('use team_time_ask_agent when you do need an answer'), so it stops short of full routing 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 declare destructiveHint=true and openWorldHint=true; the description adds real value by disclosing the human-enabled coordination prerequisite and the ownership non-claim, which is the key ambiguity for this operation. It does not explain why the call is destructive (e.g., whether existing file/branch links are overwritten), leaving a gap against a destructive=true annotation.

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, all load-bearing: the operation first, then the prerequisite, then the ownership caveat. No filler and no repetition of schema details.

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, destructive mutation with six undocumented parameters, the description covers intent and prerequisites but not effects: what happens if the run is already linked, whether prior file/branch declarations are replaced, or what the caller gets back. Adequate to invoke, not sufficient to predict consequences.

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; it does partially by naming files, branch and checkpoint and clarifying that files are repository-relative. However taskId, runId and repository are never explained, and the constraints (max 50 files, 300 char paths, uuid format) come only from the schema.

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

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

States a specific verb and resource: link the caller's own registered run to a task and declare files, branch and checkpoint. The closing line 'Linking does not claim task ownership' explicitly separates it from the sibling team_time_claim_task, which shares the same conceptual territory.

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 a concrete prerequisite ('Requires project coordination to be enabled by a human') and a clear exclusion ('does not claim task ownership'), which routes the agent away from claim_task. It stops short of naming the alternative tool explicitly or describing what to do if coordination is disabled.

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 the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add protocol detail — and it does, disclosing that responses are paginated into pages with a nextCursor and that the limit must be held constant while following the cursor. It doesn't note whether paging is stable under concurrent changes, but this is meaningful added context beyond the 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?

Two short sentences, the operation front-loaded and pagination instructions second. Nothing redundant, though the brevity comes partly from under-specification.

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

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

For a 2-param, no-output-schema, annotated read tool this is roughly adequate — safety is covered by annotations and the cursor protocol is explained. What's missing is scope: what a 'member' is and what the page items contain, which the agent needs to use the results correctly.

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 both parameters. It does clarify that 'limit' is the page size which must remain unchanged across pages, and cursor is implied via 'page.nextCursor', but it omits defaults, the maximum of 100, and what a cursor string is bound to.

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 verb 'Read' and resource 'members' are stated, which distinguishes it loosely from list_projects/list_tags/list_tasks by resource name. However, 'members' is never qualified (team? workspace? project members?), so the agent cannot tell precisely what is enumerated or how it differs from get_task_agents.

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 statement of when to call this versus the many sibling list/get tools, and no prerequisites or exclusions. The only guidance is procedural: 'Follow page.nextCursor with the same limit.'

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral information absent from annotations: results are paged and the next page is driven by page.nextCursor with a preserved limit, which is useful for pagination loops.

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, zero filler, with the core action front-loaded and the pagination contract immediately after. Every phrase 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 simple two-parameter list tool this covers the pagination contract, which is the main risk area. But with no output schema, the description only reveals one return field (page.nextCursor) and says nothing about what a project record contains, whether an empty page signals the end, or default page size.

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. It partially does: "page.nextCursor" ties the cursor parameter to the returned continuation token, and "same limit" implies limit governs page size. It does not state the default limit, what the max of 100 implies, or cursor lifetime/stability.

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?

"Read one page of projects" gives a specific verb (read/list), a specific resource (projects), and the pagination scope. It is naturally distinguishable from siblings like team_time_list_members, team_time_list_tags, and team_time_list_tasks by resource, though it never states that differentiation 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?

The second sentence gives operational guidance for continuing pagination (reuse the same limit with nextCursor), which implies this is a paged listing. However, it never says when to use this tool, when to stop, or how it relates to alternative listing tools, so usage 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 readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description does add real value by disclosing the pagination contract (follow page.nextCursor, reusing the same limit), which the agent could not otherwise know since there is 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?

Two short sentences, front-loaded with the purpose and followed by the paging rule; every clause earns its place. It is arguably too terse rather than padded, but it does not waste 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?

For a two-parameter paginated read with no output schema, the definition omits what a tag is, what the returned page shape looks like beyond nextCursor, and how to detect the final page. The pagination hint helps but leaves the agent guessing about the resource itself.

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

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

Schema description coverage is 0% for both parameters, so the description must carry the load. "One page" and "same limit" weakly imply limit is a page size and cursor is a continuation token, but neither parameter is named or explained, and the schema's maximum/minimum bounds and cursor length cap go unmentioned.

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 verb and resource are stated ("Read one page of tags"), so the agent knows this is a paginated read of tags. However, "tags" is never scoped or defined in the context of team_time, and nothing distinguishes it from siblings like team_time_list_projects, team_time_list_members, or team_time_list_tasks, which also read collections.

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 any of the many sibling list tools, no prerequisites, and no exclusions. The second sentence is continuation mechanics, not usage guidance, so the agent must infer the selection criteria entirely.

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

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

Annotations already declare readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. Beyond that the description adds two real behavioral facts: results include completed history by default, and pagination requires replaying the cursor with unchanged filters. It says nothing about result ordering, default page size, or what an empty result means.

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 tight sentences with the core capability front-loaded and zero filler. The coordination sentence is dense and slightly cryptic ('claim markers'), but it earns its place by driving filter strategy.

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?

Read-only annotations mean return-value explanation is not strictly required, and the pagination rule is a genuinely useful addition. However, for an 11-parameter, zero-coverage filter tool with no output schema, the description leaves too much of the filtering surface unaddressed for an agent to call it 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 0% across 11 parameters, so the description must carry the burden and largely does not. It touches 'query' (title search) and 'cursor' (follow every cursor with unchanged filters) and alludes to project/status filters, but leaves dueFrom/dueTo, tagIds, clientId, statusId, assigneeId, statusCategory, and limit completely 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?

States a specific verb and resource ('Search tasks') plus an explicit scope note that completed history is included, which an agent could not infer from the name. It does not name the sibling (e.g. team_time_get_task) that handles single-task lookup, 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?

Gives concrete when-to-use guidance ('For coordination, inspect ALL unfinished project tasks and claim markers') and warns that title search alone can miss overlapping work, which steers filter choice. It stops short of stating explicit exclusions or naming an alternative tool for direct task retrieval.

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/non-destructive, and the description adds value beyond them: a seven-day retention window and the fact that payloads are omitted from results. That return-shape detail is genuinely useful and not contradicted by the readOnlyHint, since the actual retry happens in a sibling tool.

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, then retention/return facts, then the recommended follow-up action. 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?

No output schema exists, and the description compensates by describing what comes back (IDs without payloads) and how long data survives. The one gap is not explicitly linking the returned command IDs to team_time_retry_command, though the 'retry the exact command' sentence strongly implies it.

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

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

The tool takes zero parameters, so the schema baseline is 4. The description correctly implies no input is needed, and nothing further about parameters is required.

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 ('Recover uncertain mutations') and clarifies the return ('command IDs without payloads'), which is enough to distinguish it from task-creation siblings. It does not name the closely related team_time_retry_command, so sibling differentiation is implied rather than explicit.

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 clear triggering condition ('after a timeout or process restart') and a concrete alternative to avoid ('instead of creating another task'). What's missing is an explicit pointer to team_time_retry_command, which is the natural next step after using this 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 destructiveHint=true and idempotentHint=false, but the description never explains those traits — it does not say what registering overwrites, or what happens if the same chat is registered twice. It does add one useful piece of behavioral context not in structured fields: the return value (runId) used for linking and replies. No contradiction with the write 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?

Three short sentences, front-loaded with the action, then the parameter rule, then the return value. Nothing is padded, though the final return-value sentence could be folded in more tightly.

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 absence of an output schema makes the runId disclosure valuable, and the sessionId sourcing rule is a real contribution. However, for a non-idempotent, destructive mutation the description omits duplicate-registration behavior and any note on what the bridge does with an existing chat, leaving a material gap.

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 the parameter burden. It meaningfully constrains sessionId (source it from hook context or the host, never guess), but leaves 'name' completely unexplained — it is unclear whether it is a display name, a chat title, or an identifier used for lookup.

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: 'Register this native Codex chat with the shared local bridge.' That is concrete and distinguishable from list/claim/reply siblings, but it never names team_time_link_agent_chat or team_time_bootstrap, which an agent could plausibly confuse with registration.

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 line 'Supply sessionId from hook context or the host; never guess another chat ID' gives a sourcing rule rather than when-to-use guidance. There is no statement of when this should be called versus team_time_link_agent_chat, or what a caller should do if the chat is already registered.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the mutation/irreversibility profile is partly covered. The description adds a useful handoff prerequisite sequence and a concurrency-adjacent safety rule about not releasing another run’s claim, but it does not explain what releasing destroys, how expectedVersion conflicts are handled, or whether the release can be retried.

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, followed by the handoff prerequisite and the safety constraint. There is no filler, and each sentence contributes operational meaning.

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 covers purpose and when to call, but for a destructive, non-idempotent tool with three required undocumented parameters and no output schema, it omits crucial details: parameter meanings, expectedVersion behavior, and what a successful release returns. It is not complete enough for confident invocation without inspecting the schema further.

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 three required parameters, so the description must compensate and largely does not. 'This run’s claim' loosely implies the claimId, but taskId and especially expectedVersion (optimistic concurrency) are left unexplained, which is a significant gap for correct invocation.

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: 'Release this run’s claim.' The qualifier 'this run’s claim' distinguishes it from sibling operations like team_time_claim_task, but it does not explicitly name a sibling alternative or describe the broader claim lifecycle.

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 clear usage context: call this 'after completing or handing off work,' and for handoff, first 'save a checkpoint and set a not-started status.' It also states an important exclusion ('Never release another run’s claim automatically'), though it does not name sibling tools that may be needed for those prerequisite steps.

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=true, non-idempotent, openWorld, so the bar is lower; the description still adds real behavior — late replies remain labeled late, and replies may not target reply messages or stand in for another run. It doesn't explain why the call is destructive (whether it consumes/closes the message) or who can see the reply, which keeps it from a 5.

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, purpose first, then the two hard constraints. No filler and nothing buried.

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 and key guardrails but leaves ambiguity for a destructive, state-changing messaging tool with no output schema: what happens to the original message, what "late" means operationally, and what a successful reply returns are all unstated.

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; it implies runId is the addressed run and messageId is the question/note being answered, but never states UUID formats, body limits (2000 chars), or that all three are required.

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) and resource (a task question/note), and pins the actor to "the addressed run". It is distinguishable from siblings such as team_time_leave_agent_message or team_time_ask_agent, though the term "addressed run" is domain jargon left undefined.

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 explicit when-not guidance: "Never reply to reply messages or impersonate an old run." However it never names the alternative tool for those cases (e.g., leave_agent_message or ask_agent), so the routing decision is only half-specified.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds non-obvious semantics the annotations cannot express: version state is not rebased and credential access is rechecked at replay time. What is missing is failure behavior when the retained command has expired.

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, then the trigger, then the caveats. No wasted words and nothing buried.

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 a single required param, no output schema, and annotations covering the safety profile, the definition is nearly sufficient but leaves two operational gaps: how to acquire a valid commandId and what a replay failure returns. Those are exactly the things an agent needs before calling a destructive replay 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?

There is one parameter at 0% schema description coverage, so the description must carry the load. It implies the UUID identifies the retained mutation, but never says where to obtain commandId (presumably team_time_pending_commands) nor what happens if the UUID is unknown or already replayed.

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 (replay) and resource (retained mutation), and enumerates what is replayed: original UUID, method, path, payload. An agent can distinguish it from team_time_pending_commands (which presumably lists rather than replays), though the description never names that 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?

"Use after an uncertain response" is a concrete trigger condition, and the two follow-on sentences implicitly define when-not-to-rely-on-it (stale versions are not rebased). It stops short of naming the alternative action, e.g. issuing a fresh command or calling team_time_pending_commands to find the ID.

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 destructiveHint=true and idempotentHint=false, but the description adds material context beyond them: optimistic concurrency (it will not silently overwrite a stale version) and a concrete side effect ('Completion may stop the key creator's matching timer'). That side-effect disclosure is exactly what an agent needs before calling a destructive mutation. It does not say what happens on a version mismatch (error vs. no-op) or what the response 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?

Four short clauses, no filler, with the core action front-loaded and the safety warning at the end. Slightly dense jargon ('discovered workflow status', 'key creator') costs a bit of readability but nothing is wasted.

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

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

For a destructive, open-world mutation with six parameters, no schema descriptions, and no output schema, the description covers the concurrency contract and one side effect but omits error behavior on stale versions, the meaning of `result`, and how to obtain valid statusIds or current versions. Adequate but with clear gaps an agent would hit on first 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 0%, so the description carries the load. It meaningfully explains claimId (only when claimed), expectedVersion/expectedWorkflowVersion (must reflect observed state, never stale) and statusId (must be a discovered workflow status). It leaves the required taskId and the optional `result` parameter entirely unexplained, so it only partially compensates for the coverage gap.

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 verb+resource combination ('Move to a discovered workflow status') is specific enough to identify a status-transition operation on a task, and the mention of task/workflow versions distinguishes it from siblings like team_time_complete_task or team_time_update_task. It stops short of naming the object being moved (a task) or pointing at team_time_workflow as the source of valid statuses.

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?

'Include claimId if claimed' is a real conditional-use rule, and 'Never automatically overwrite a stale version' implies the version-check contract. However, the description never states when to use this tool rather than team_time_complete_task or team_time_update_task, nor where to obtain a 'discovered' status or the observed versions.

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 flag destructive, non-idempotent, open-world behavior, and the description adds real value beyond them: omitted fields stay unchanged, null clears assignee/due date, [] clears tags. It omits the conflict/version behavior implied by the required expectedVersion, which is the main remaining gap.

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 and front-loaded: mutability semantics come first, then the clearing rules, then claimId and result. No filler, though the final clause about checkpoints is slightly vague.

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 destructive mutation with no output schema and zero schema descriptions, the definition is close but incomplete — it never explains that expectedVersion must match the version read back, which is essential to calling it successfully.

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 meaning, and it does explain tags, assigneeId, dueOn, claimId and result. It says nothing about expectedVersion (a required optimistic-concurrency token), projectId, title, description or taskId, leaving half of 10 params undocumented anywhere.

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 ('Update ... fields') plus scope ('only supplied fields'), which distinguishes it from whole-record siblings like create_task. It does not, however, contrast itself with set_status or complete_task, which also mutate tasks.

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?

'after reading the task' and 'Supply claimId for claimed work' give concrete preconditions for correct invocation. It stops short of naming when to prefer a sibling (e.g. set_status for simple status changes) or rules for when not to update.

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 meaningful context beyond the annotations: a 10-second per-call cap bounded by the original server deadline, prompt return on reply/timeout/incoming question, and a one-minute cumulative budget. It does not describe what the returned reply or question payload looks like, which keeps it short of a 5.

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, each carrying a distinct rule, with the per-call cap front-loaded before the loop guidance. Nothing is redundant or restated from 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?

The behavioral picture of the wait is complete enough to drive a polling loop, but with 0% schema description coverage and no output schema, the description leaves the identity of the three required parameters unexplained. For a tool whose correctness depends on tracking messageId/runId across iterations, that is a notable gap.

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 none of the four parameters (messageId, installationId, runId, seconds) are explained in the description. The mention of 'at most 10 seconds per call' indirectly hints at the seconds parameter's ceiling, but the three required UUID identifiers are undocumented in both the schema and 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?

The description makes clear this is a bounded wait/poll for an agent reply, with the verb ('wait') and the resource (agent reply) stated. It distinguishes itself implicitly from fetch-style siblings like team_time_get_agent_message or team_time_reply_agent_message by emphasizing blocking behavior, but 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?

It gives concrete operational rules for the polling loop: 'Process incoming questions before waiting again' and 'Never wait more than one minute total.' That is real when-to-use guidance, though it doesn't state when to skip waiting entirely (e.g. go read the inbox or call get_agent_message directly).

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 the returned content (status IDs, categories, workflow version), which matters because there is no output schema, but says nothing about freshness, caching, or failure modes.

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 no waste, but it is terse enough that it leaves questions about return shape and version semantics unanswered.

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 tool with no output schema, the description covers what comes back and why it is called early. The main gap is whether results are cached or must be re-read after workflow changes.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly does not invent parameter discussion.

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 (Read) and the resources returned (status IDs, categories, workflow version), so the agent knows exactly what this tool fetches. It does not name a sibling, but the phrase 'before changing task status' implicitly separates it from mutators like team_time_set_status.

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 clear trigger condition: call this before changing a task's status. It does not spell out when-not-to-use or name an explicit alternative, but for a no-parameter prerequisite lookup the context is sufficient.

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