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

With no annotations supplied, the description carries the full burden, and 'List' at least signals a non-mutating read. However, it discloses nothing about whether results are scoped to a workspace, whether stale agents are included, ordering, or pagination/limits — details an agent would need before relying on it.

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 filler; the resource comes first and the returned fields follow. Nothing could be cut without losing 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 zero-parameter, read-only listing with no output schema, naming the returned fields (roles, capabilities, last-seen) covers most of what an agent needs. Minor gaps remain around result scope and whether the list is bounded, but the tool's simplicity keeps this near-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 tool takes zero parameters, so there is no argument meaning for the description to add; baseline is 4. The sentence correctly implies an unfiltered, full listing, which matches the empty 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 ('List registered agents') and previews the payload ('roles, capabilities, and last-seen times'), so an agent knows exactly what it gets back. It does not distinguish itself from nearby siblings like bus_status or bus_search, which may also surface agent information, 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?

Usage is only implied by the verb 'List' — an agent can infer this is the discovery call for agents, but the description never says when to prefer it over bus_status, bus_search, or bus_channels, nor whether registration (bus_register) is a prerequisite. 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?

With no annotations, the description usefully discloses a state-changing operation and its queue-release effect. It does not cover authorization requirements, failure behavior, repeat approvals, or what the tool 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?

The single sentence is compact, front-loaded with the operation, and includes both the precondition and effect. There is no redundant or unnecessary wording.

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 core lifecycle transition is clear enough for a simple two-parameter tool, but correct invocation still requires guessing the parameter semantics. Missing permission and error behavior further limit completeness in the absence of annotations and an output schema.

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 does not explain either required parameter. In particular, it never clarifies that id identifies the task or what agent represents, how to obtain it, or whether it controls authorization.

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 specifies the verb, resource, required task state, and resulting action: approving a task in needs-approval releases it to the queue. This clearly distinguishes it from sibling tools for claiming, completing, cancelling, or creating 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?

It explicitly establishes that the tool applies to a task waiting in needs-approval, providing a clear usage condition. It does not state what happens for tasks in other states or identify any alternative tool for those cases.

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

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

With zero annotations provided, the description is solely responsible for behavioral disclosure. Simply stating 'Cancel' provides almost no operational context regarding preconditions or guaranteed outcomes.

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 extremely concise and avoids any unnecessary filler, communicating the tool's function in a single, highly dense sentence.

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 tool within a large suite of task management functions, the description is insufficient. It lacks detail about preconditions, such as ensuring the task is indeed 'open' before cancellation.

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

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

The input schema has 0% description coverage, and the description fails to provide meaning for the required parameters 'id' or 'agent'. The agent must infer what these IDs represent.

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 direct action verb and identifies the specific resource (open task) being manipulated. This provides clear semantic intent.

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

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

There is no guidance on when to use this tool relative to similar state-changing siblings, such as bus_complete_task or bus_claim_task, forcing the agent to guess the correct 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?

With no annotations, the description carries the full behavioral burden and discloses almost nothing beyond the fact that it reads. It does not say whether results are ordered, paginated, filtered by membership, or whether auth/registration is required — notable given bus_register and bus_rotate_token exist as siblings.

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 filler, which is appropriate for a trivial no-arg listing tool. It is arguably too terse, but nothing in it is wasted.

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

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

For a zero-parameter read tool with no output schema, the core need is knowing what comes back and in what shape. The description explains the output conceptually (channels + counts) but omits ordering, scope, and whether this requires prior bus registration.

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. It does at least identify the returned fields (channel names with message counts).

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 concrete verb ('List') and resource ('message channels') plus the payload ('message counts'), so an agent knows exactly what it retrieves. It stops short of distinguishing itself from siblings like bus_agents, bus_status, or bus_search, which could plausibly also enumerate bus entities.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of any sibling alternative. The agent must infer that this is a discovery call to enumerate channels before send/inbox/thread operations.

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

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

With no annotations, the description carries the full burden and does disclose the two most important behavioral traits: exclusivity of the claim and a 15-minute lease, plus the failure mode when contended. It does not say what happens when the lease expires mid-work, whether the lease is renewable, or what the tool returns on success vs failure.

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 action and the exclusivity constraint, then the failure condition. 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?

For a mutation tool with zero annotations, no output schema, and undocumented parameters, the description covers the lease and contention behavior well but leaves parameter meaning and post-claim lifecycle (renewal, expiry, release) unexplained. Adequate minimum, but clear gaps for a state-changing tool.

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

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

Schema description coverage is 0% and the description never mentions either parameter. An agent must guess that 'id' is the task identifier and 'agent' is the claiming agent's identity string, and gets no hint about whether 'agent' must match a registered identity from bus_register.

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 ('Claim a queued task') and adds the defining scope qualifier 'exclusively', which separates it from sibling read tools like bus_list_tasks and follow-on actions like bus_complete_task. It stops short of naming an explicit alternative, so sibling routing is inferred rather than stated.

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?

'Fails if another agent holds it' gives the agent a clear precondition to check before calling, which is real usage guidance. However, there is no explicit when-to-use-vs-alternatives guidance (e.g. vs bus_approve_task or bus_list_tasks), and no guidance on what to do after a failed claim.

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

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

No annotations are supplied, so the description carries the full burden. It does not say whether commenting requires authentication (the token parameter suggests it might), whether comments are append-only, whether the comment notifies anyone, or whether it is recorded in the task history it mentions.

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

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

A single short sentence with the action front-loaded and the clarification tucked into a parenthetical. Nothing is wasteful, though the parenthetical adds little practical detail.

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

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

For a four-parameter mutation tool with no annotations and no output schema, the description is too thin. It omits auth requirements, expected identifier semantics, and what happens on success or failure.

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 all four parameters (id, body, agent, token) are undocumented. The description only weakly implies that id is the task and body is the comment text; it says nothing about what agent means or how token is used.

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: 'Comment on a task'. The parenthetical clarifies where the comment is stored, so the agent knows this adds to the task's discussion. It does not distinguish itself from siblings like bus_thread or bus_send, which also carry messages.

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 or when-not-to-use guidance. The parenthetical implies task-scoped discussion versus a general thread, but the agent is not told when to choose this over bus_thread, bus_send, or bus_events.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It usefully notes that the result summary is delivered to the sender, but says nothing about state transitions, whether completion is reversible, what happens if the task was never claimed, or what the caller receives back.

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

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

One short sentence with the action and the key precondition front-loaded and no wasted words. The brevity comes at the cost of under-specification rather than verbosity.

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 mutation tool with no annotations, no output schema, and zero schema coverage needs considerably more description to be safely invocable. The precondition and the result parameter are covered, but the agent identity, task id semantics, and outcome behavior are all missing.

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

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

Schema description coverage is 0%, so all three parameters rely on the description. Only the optional "result" parameter is addressed (as a summary for the sender); "id" and "agent" are never explained, leaving the agent to guess whether "agent" is the caller's own identity or a target.

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?

"Complete a task you claimed" gives a specific verb (complete) and resource (task), plus the precondition that the task must already be claimed, which separates it from bus_claim_task or bus_create_task. It stops short of distinguishing itself from bus_approve_task or bus_cancel_task, which are the closest alternatives in the sibling list.

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

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

The description implies the when-to-use condition by requiring the task be one "you claimed," but gives no explicit guidance on how this differs from bus_approve_task or bus_cancel_task, nor what to do when a task isn't claimed.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that this is a creation operation and that tasks can be optionally assigned, marked urgent, or gated behind approval, but it omits permissions, side effects, notification behavior, and what happens when needsApproval is true.

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 front-loaded, uses one efficient sentence, and includes no wasted wording. The parenthetical mapping to needsApproval is compact and useful.

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

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

For a 7-parameter creation tool with no annotations, no output schema, and 0% schema description coverage, the description is too thin. It covers the core purpose and some optional behaviors but leaves required parameters, dependencies, and return behavior unspecified.

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 parameters, so the description must compensate. It adds meaning for assignee, priority, and needsApproval, but leaves the required agent and title fields, plus body and blockedBy, unexplained.

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

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

The description states a specific verb and resource: "Create a handoff task." This is clearer than a tautology and distinguishes creation from sibling task actions like claim, complete, and cancel. It does not explicitly contrast those siblings, 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?

Usage is implied by "Create a handoff task," and the optional assignment, urgency, and approval gate are mentioned. However, it gives no explicit when-to-use guidance versus adjacent tools such as bus_approve_task, bus_claim_task, or bus_list_tasks.

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

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

No annotations exist, so the description carries the full burden. 'Read' implies a non-mutating operation and the phrase 'provenance event log' hints at an audit trail, but ordering, retention, pagination behavior, and access requirements are all 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?

One short, front-loaded sentence with no filler. It is efficient, though its brevity contributes to the gaps elsewhere rather than earning extra credit.

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 one-parameter read tool this could suffice, but with no annotations, no output schema, and an undocumented limit, the definition leaves the agent guessing about return shape and result volume. It should at least explain the limit and what a provenance event contains.

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 single parameter 'limit' has 0% schema description coverage and is never mentioned in the description. The agent gets no explanation of what the limit bounds (events returned?), what happens beyond the default of 50, or whether truncation is indicated.

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 resource (the provenance event log) plus a parenthetical clarifying its content as who did what and when. This distinguishes it from siblings like bus_search or bus_status without naming them, so it is clear but lacks explicit sibling differentiation.

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

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

There is no guidance on when to use this log versus bus_search, bus_status, or bus_channels, and no stated preconditions. The agent must infer that this is the audit-trail endpoint from the phrase 'provenance event log' alone.

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

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

With no annotations, the description carries the full burden; it does disclose the key side effect (marking the agent present) and what comes back (agent list with online status), which is meaningful. However, it says nothing about authentication expectations for the token, whether presence expires, or whether the call is idempotent or rate-limited.

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

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

A single sentence that front-loads the operation and follows with the return value; there is no filler and nothing redundant.

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 tool with no annotations and no output schema, the description partially compensates by stating the return shape, which is helpful given the missing output schema. The unexplained token parameter and absent lifetime/auth behavior for a presence-mutating call leave real 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 description coverage is 0% for two parameters, so the description must compensate. It only implicitly identifies 'agent' via 'this agent' and never mentions the token parameter at all, leaving a required credential's meaning and behavior undocumented in both the schema and the prose.

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 action ('mark this agent present') and a specific return ('get the live agent list with online status'), distinguishing it from pure lookups like bus_agents or bus_status. It does not explicitly say how it differs from those siblings, which keeps it from 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 heartbeat framing implies when to call it (periodic presence refresh), but there is no explicit statement of when to prefer it over bus_agents, bus_status, or bus_register, nor any exclusion or prerequisite. Usage must be inferred from the word 'Heartbeat'.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key side effect that messages are marked read unless markRead=false, which is the most important mutation to flag. It does not mention pagination, ordering, default limit behavior, or what happens when unreadOnly and markRead interact.

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 tight sentence with the scope front-loaded and the side effect trailing. Nothing is wasted, though the density means two distinct concepts (visibility scope and read-marking) are packed without separation.

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 4-parameter read tool with no annotations and no output schema, the description covers purpose and the destructive-adjacent markRead behavior but leaves limit, unreadOnly, and the return shape unexplained. An agent can call it, but cannot predict ordering or page boundaries.

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

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

Schema description coverage is 0%, so the description must compensate, and it does explain the two most consequential parameters: agent scope (visible to this agent) and markRead (with its false escape hatch). limit and unreadOnly are left entirely to the bare schema types and defaults, so the coverage is partial rather than complete.

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 (read messages) and enumerates the visibility scope: direct, broadcast, and its own. This distinguishes it from write-side siblings like bus_send and search-side siblings like bus_search, though it never names those alternatives 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 parenthetical scope note implies when this tool is appropriate (checking what has arrived for an agent), but there is no explicit when-not guidance, no mention of bus_search or bus_events as alternatives, and no prerequisites such as registration or token state.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It never states that this is a read-only operation, whether results are paginated, how they are ordered, or whether there is a default/maximum result count — all relevant for a list endpoint on a busy bus.

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

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

One front-loaded sentence with zero filler, and the resource is named before the optional filters. It is efficient, though the brevity borders on under-specification for a list endpoint.

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-optional-parameter list tool with no output schema and no annotations, the description should say what comes back and how much. It omits return shape, ordering, result limits, and valid status values, leaving the agent to call it blind on a key read path.

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 schema contributes nothing beyond bare string types; the description is the only source of meaning. It does map both parameters to intent (status filter, assignee/claimer filter) and usefully notes the claimer alias, but it gives no accepted status values despite no enums being defined in 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: "List tasks," with the added scope that filtering is optional. It is clearly distinct from the mutation siblings (bus_create_task, bus_claim_task, bus_complete_task), though it never explicitly names a read-alternative like bus_search or bus_inbox to route against.

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?

"Optionally filtered by status or assignee/claimer" implies the calling context (browse/filter the task list), but there is no explicit when-to-use versus bus_search or bus_inbox, and no statement of when a filter should be applied. 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?

With no annotations at all, the description carries the full burden and does well: it discloses the critical side effect that the per-agent token is returned ONCE on first registration and must be stored, plus the conditional requirement to pass it as `token` on later calls. It does not address idempotency of rejoin (does a rejoin issue a new token or reuse the stored one), which is the main open behavioral question.

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 followed immediately by the one detail that causes real failures if missed (store the one-time token). 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 and no annotations, but the description covers the highest-risk aspect (one-time token issuance and reuse). Gaps remain around rejoin semantics and the meaning of the `agent` identifier, which matter for a registration tool.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate. It explains the purpose of `token` and loosely maps `role`/`capabilities`, but the only required parameter, `agent`, is never explained 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?

The description names a specific verb and resource (register/rejoin this agent on the bus) and states the payload semantics (role and capabilities). It is clear enough to distinguish from bus_rotate_token or bus_heartbeat by intent, though it never names a 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?

The parenthetical '(or rejoin)' implies this is both the first-contact and reconnect path, and the token sentence implies later calls are token-enforced. There is no explicit statement of when to prefer bus_rotate_token, bus_status, or bus_heartbeat, or what to do if registration fails.

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

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

With no annotations, the description carries the behavioral burden and does disclose the two critical traits: the old token stops working (irreversible invalidation) and the new one is shown only once (must be captured immediately). It does not cover failure modes, whether other sessions are dropped, or who is authorized to rotate.

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 action, then the consequences. No filler or redundant restatement of the tool name.

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

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

For a small two-parameter mutation with no output schema or annotations, the description covers the essentials an agent needs: the credential prerequisite and the irreversibility/one-time-display behavior. Only authorization and failure behavior are left implicit.

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 clarify that 'token' is the current token required only on an enforced bus, which explains why that parameter is optional, but it says nothing about the required 'agent' parameter's accepted format or whether it can name a different agent.

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 ('Rotate ... token') scoped to an agent, which no sibling tool duplicates. The phrase 'this agent's' is slightly at odds with the required 'agent' parameter, leaving a small ambiguity about whether it acts on the caller or on a named agent.

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 prerequisite condition ('requires the current token on an enforced bus') that signals when the extra credential is needed. It gives no guidance on when to rotate versus leave a token alone, nor any mention of alternatives or admin scenarios.

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

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

With no annotations, the description carries the full behavioral burden. "Search" suggests a read operation, but the description does not confirm read-only behavior or explain matching, result ordering, access scope, or pagination.

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

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

The single sentence is front-loaded with the action and efficiently communicates the searchable resource types. There is no unnecessary wording.

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?

This is adequate for basic selection of a simple two-parameter search tool, but gaps remain because there are no annotations, output schema, or parameter descriptions. The agent still lacks information about result contents, search visibility, and result-limiting behavior.

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 "by text" provides only basic meaning for query. The description does not explain query syntax or matching behavior, and it adds nothing about how limit affects results beyond the schema's name, type, and default.

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, resource scope, and method: searching messages, tasks, and shared files by text. This is clear alongside the list and inbox siblings, although it does not explicitly differentiate itself from them.

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 wording implies use when the agent has a text query rather than merely wanting to browse resources. It does not state when to prefer alternatives such as bus_inbox, bus_list_tasks, or workspace_list_files, nor any when-not guidance.

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

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

No annotations are supplied, so the description carries the full burden. It discloses routing semantics but nothing about delivery guarantees (live push vs stored in an inbox), what happens when the named agent does not exist, whether the message is persisted, or any auth/rate constraints. For a write-style messaging tool with zero annotation coverage, this leaves real behavioral questions open.

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 primary action and with the broadcast case stated before the threading detail. Nothing is padded, though the compression contributes to the ambiguity around the 'agent' parameter.

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?

Five parameters, no annotations, no output schema and no schema descriptions make this a complex tool resting on a two-sentence description. Too little is said about the required 'agent' field, the 'channel' scope, or the result of the call for an agent to invoke 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 five parameters, so the description is the only source of meaning — and it only explains 'to' and 'threadId'. Critically, the required 'agent' parameter is never mentioned alongside 'to' (which defaults to '*'), leaving an agent unable to tell whether they duplicate or differ; 'body' and 'channel' (default 'general') are also 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 ('Send a message') and immediately covers both delivery modes: direct to one agent or broadcast via '*'. That distinguishes it from siblings like bus_inbox and bus_thread, though the overlapping required 'agent' parameter is not reconciled with 'to'.

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 usage for the routing parameters ('to = its name' vs 'to = "*"') and for threadId as a reply mechanism, so the two main call patterns are discoverable. It offers no guidance on when to use this versus alternatives like bus_comment_task or bus_create_task, nor any prerequisites such as whether the target agent must be registered 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?

No annotations are supplied, so the description carries the full disclosure burden, yet it never states that the call is read-only with no side effects, whether it requires authentication/workspace scoping, or how fresh the counts are. Only the parameterless shape hints at a safe, side-effect-free read.

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 terse line with the resource front-loaded and no filler. It is telegraphic rather than ungrammatical, and nothing is redundant.

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 source of return information, and it enumerates the categories returned (agents, message/task/file counts, version) adequately. It omits the response shape and any caveats, which leaves a modest gap for a zero-parameter status 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?

The tool takes zero parameters, which is the baseline-4 case; nothing in the input schema needs elaboration. The description correctly implies no inputs are required to obtain the snapshot.

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 the resource (workspace status) and enumerates the contents (agents, message/task/file counts, version), so an agent can infer it is a read-only snapshot of the workspace. However, it is a noun fragment with no verb, and it does not distinguish itself from siblings such as bus_agents or bus_channels, which return overlapping slices of the same data.

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

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

There is no guidance on when to call this versus the many sibling listing tools (bus_agents, bus_channels, bus_list_tasks, workspace_list_files). No prerequisites, no exclusions, no indication that this is the cheap overview call before drilling into a specific sibling.

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

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

With no annotations, the description carries the full burden. It does disclose the return contract ('Returns headSeq to store as the next cursor') and the catch-up replay semantics, which is real value. It is silent on read-only/destructive nature, ordering guarantees, and what happens when no events exist or when the result is truncated by the default 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 short sentences, zero filler, and the core scoping concept (catch-up after a sequence number) is front-loaded before the return-value note. 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?

For a 2-parameter, annotation-free tool with no output schema, the description covers purpose, use case, and the key return field. It is not complete enough: pagination/limit behavior and the absence of any safety or idempotency statement leave gaps an agent would have to discover by calling.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the cursor model for sinceSeq well ('after a sequence number', headSeq as next cursor), but it never mentions limit (default 500) or its page-size meaning, leaving one of two parameters 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?

The description uses a specific verb and resource: 'Catch-up sync: all provenance events after a sequence number.' The parenthetical explains the exact intent (offline replay) so an agent can distinguish this from a general listing call. It never names a sibling like bus_events, 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?

It gives a clear scenario for use: an agent that was offline replays exactly what it missed, driven by a stored cursor. It does not state when NOT to use it or point to bus_events/bus_search as the alternative for live or filtered queries, so the guidance is contextual but 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?

No annotations are supplied, so the description carries the full burden. It does disclose the return shape (root message + replies), which is genuinely useful, but says nothing about read permissions, whether historical or deleted replies are included, ordering, depth limits, pagination for long threads, or behavior when the id does not exist.

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

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

A single front-loaded sentence with zero filler; the parenthetical scope note earns its place by defining what is returned.

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 no output schema, the description adequately conveys the shape of the result. However, with zero schema documentation on the id parameter and no annotations, the definition leaves the agent guessing about id semantics and error behavior.

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 single required parameter is bare `id: number`. The description does not clarify whether the id is the root message id, any message id within the thread, or a thread id — a distinction that materially changes the call. This is the main gap for a one-parameter tool.

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 ("Read a message thread") and parenthetically defines the scope as the root message plus its replies, which distinguishes it from bus_inbox and bus_search. It does not name any sibling explicitly, so an agent must infer the boundary from the verb alone.

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

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

There is no when-to-use guidance, no prerequisite (e.g. needing a thread/message id obtained from bus_inbox or bus_search first), and no statement about what to do when the id is unknown or the thread is empty. Usage is only implied by the verb "Read".

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

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

With no annotations, the description must carry the behavioral burden, and it does disclose the content scope of what comes back. It does not state that the operation is read-only, whether results are truncated or how "recent" activity is bounded, nor anything about size or ordering. Useful content disclosure, but gaps remain.

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 a verb, an object, and a colon-delimited content list. Nothing is redundant and nothing could be removed without losing 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 zero-parameter aggregate read with no annotations and no output schema, the description effectively doubles as a return-value summary. The only shortfall is the absence of any note on scope, freshness, or truncation of the board contents.

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 are no parameter semantics to explain and the baseline is 4. The description correctly does not waste space on nonexistent inputs.

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 pairs a specific verb ("Render") with a specific resource ("the shared board") and enumerates its contents (agents, open tasks, files, recent activity). This implicitly distinguishes it from single-domain siblings such as bus_agents, bus_list_tasks, and workspace_list_files by making clear it is an aggregate view, 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?

No explicit when-to-use or when-not-to-use guidance is given, and no alternative is named. However, the enumerated contents imply the intended use case: a single overview instead of several per-domain calls. That is implied rather than stated, so it stays at 3.

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

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

No annotations are supplied, so the description carries the full burden for a destructive operation, yet it says nothing about irreversibility, overwrite behavior, required permissions, or what the 'token' parameter implies. The word 'Delete' conveys the mutation, but nothing beyond that basic inference is provided.

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

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

One front-loaded sentence with no wasted words, which satisfies the structural bar. However, the brevity is under-specification rather than effective conciseness for a destructive tool with three undocumented parameters.

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 file operation with no annotations, no output schema, and 0% parameter documentation, the description should disclose irreversibility, auth requirements, and path semantics. None of that is present, so an agent knows the action but not how to invoke it safely.

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 does not mention any of the three parameters. The meaning of 'path' (relative vs absolute, workspace-scoped?), 'agent', and the optional 'token' (auth? identity?) is 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 ('Delete') and resource ('shared workspace file'), which lets an agent distinguish it from the put/get/list siblings on the same resource. It does not explicitly name or contrast with those siblings, 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 guidance on when to delete versus when to use workspace_put_file, workspace_file_history, or any alternative, and no stated prerequisites. The agent must infer all usage context from the tool name alone.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful behavioral fact: the result is capped at the current version plus at most 10 previous ones. It says nothing about whether history is truncated for older files, whether the caller needs any permission, or what each version entry contains (revision id, timestamp, author), which matters because 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?

One short sentence with zero filler, and the most decision-relevant detail (the 10-version cap) is present rather than buried. 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 single-parameter read tool this is close to adequate, but with no output schema the description should say what a version entry looks like and how an agent would actually retrieve an older revision, since no sibling tool appears to serve that purpose. The version cap is the only structural detail given.

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, and schema coverage is 0%, so the description must compensate. It implies the single path identifies 'a shared file', which lightly clarifies the parameter's meaning, but adds no format, relative-vs-absolute, or scoping detail beyond 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?

Names a specific resource and scope: version history of a shared file, with the returned window spelled out (current + up to 10 previous). An agent can distinguish this from workspace_get_file by the word 'history'. It stops short of 5 only because it doesn't explicitly contrast itself with sibling retrieval tools.

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 contains no when-to-use or when-not-to-use guidance and names no alternative tool. An agent must infer that this is the tool for inspecting prior revisions rather than fetching content, and there is no hint about whether workspace_get_file should be called 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?

With no annotations, the description carries the full burden. It does disclose the section layout of the returned capsule and the notable side effect that create=true writes a new capsule from a template, which is genuinely useful. It omits what happens when the capsule is absent and create=false, whether creation is idempotent or destructive, and any auth requirement implied by the token parameter.

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 core action and the returned structure, with no filler. The conditional clause is attached where it matters most.

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 shape of the return value, which matters since there is no output schema, and flags the one write-capable branch. Against five undocumented parameters and no annotations, though, it leaves key invocation questions (token, agent, missing-capsule behavior) unanswered.

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 five parameters, yet the description explains only create=true semantics. slug format, agent, title, and especially token (an auth-looking parameter) are left entirely undocumented in both schema and prose, so an agent cannot tell what to pass or why.

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 ("Read a project capsule") and defines what the capsule contains (State / Decisions (locked) / Next / Session log), which distinguishes it from the context tools in the sibling list. It does not explicitly name workspace_update_capsule as the write-side counterpart, but the read framing is unambiguous.

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

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

The description implies when to use it (reading shared structured memory) and adds one conditional behavior (create=true). It gives no explicit guidance versus workspace_get_context or workspace_update_capsule, and no prerequisites such as whether a token or existing capsule is needed.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing. "Read" implies a non-mutating operation, but the description says nothing about what happens when no context has been set (error vs empty), what the object contains, its size, or whether it is scoped per workspace/agent. For a tool with zero annotation coverage this is a real 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?

A single short sentence with the verb front-loaded and no padding or filler. It is efficient, though the brevity shades into under-specification rather than disciplined conciseness.

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, no annotations, and no parameters, the description is the only channel for telling an agent what comes back — and it does not. An agent cannot tell the shape of the returned context, whether it can be empty, or how it differs from sibling read tools like workspace_get_capsule.

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 no parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The one thing worth noting — that the target context is identified implicitly by session rather than by an id argument — is left unstated, which keeps this from a 5.

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 the shared context object" gives a verb (Read) and a resource (shared context object), so the basic operation is inferable. However, the resource is never characterized — the sibling list contains workspace_get_capsule, workspace_board, and workspace_get_file, and nothing in the description tells an agent what distinguishes a "context object" from a capsule, a board, or a file. The name/title already conveys as much as the sentence does.

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

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

There is no when-to-use guidance at all: no mention of the natural pairing with workspace_put_context, no statement of when the context object exists versus when it is empty, and no routing against workspace_get_capsule or workspace_board. The agent must guess from the name alone.

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

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

With no annotations, the description carries the full burden. 'Read' implies a non-mutating operation but nothing states whether a missing path errors, whether paths are workspace-relative, or what the response contains (text vs binary), which matters because there's 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?

A single front-loaded sentence with no waste, but it's under-specified rather than concise; the brevity comes at the cost of needed detail.

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 file-read tool with no annotations, no output schema, and an undocumented parameter, the definition should cover path semantics and return behavior. Neither is present, leaving real gaps for correct 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% for the single 'path' parameter. The description adds no format, root-relative vs workspace-relative, or validation detail, so the schema and description together leave the parameter effectively 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 and resource: 'Read a shared workspace file.' The counterpart workspace_put_file is implied but not named, and it isn't distinguished from workspace_get_context or workspace_file_history, so it stops short of 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 when-to-use guidance, no mention of when to use workspace_get_context, workspace_file_history, or workspace_list_files instead, and no stated preconditions. The agent must infer everything from the tool name.

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

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

No annotations are supplied, so the description carries the full burden, yet it only discloses two returned fields. It says nothing about ordering, pagination, whether listing is recursive, whether all files or only shared ones are included, or any permission requirements — all relevant for a zero-argument tool that enumerates remote state.

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 filler; the resource and the returned attributes are both stated immediately. Nothing could be trimmed without losing 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 trivial zero-argument list tool with no output schema, the description covers the essentials of what comes back. However, it omits ordering, result-size limits, and whether the listing is scoped to a workspace, leaving gaps an agent would want before invoking it blindly.

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 and the baseline of 4 applies. The mention of 'size and last writer' in the description usefully ties to the response shape rather than to any input.

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

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

The description uses a specific verb ('List') with a specific resource ('shared workspace files') and even names the payload fields ('size and last writer'). It is distinguishable from siblings like workspace_get_file and workspace_file_history, though it never explicitly contrasts itself with them.

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

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

Usage is only implied: an agent can infer this is the entry point for browsing a workspace before calling workspace_get_file. There is no explicit when-to-use, no mention of alternatives, and no stated prerequisites such as needing a workspace identifier.

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

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

No annotations are supplied, so the description carries the full behavioral burden for a mutation tool. "Publish" implies a write, but the description never says whether this replaces existing context wholesale, whether it is idempotent, who may publish, or what happens to concurrent readers — all material for a tool described as state "every agent reads first".

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 filler. It is efficient, though the terseness is partly the cause of the missing semantics rather than a virtue in itself.

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 required two-parameter write tool with a free-form nested object, no annotations, and no output schema, the description is too thin. An agent knows roughly what to do but not the shape of the payload, the overwrite behavior, or the identity semantics of "agent".

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 context parameter is an untyped nested object, so the description must compensate. It only hints that "context" is project state; it says nothing about what "agent" identifies (name, id, role) or what fields the context object should contain.

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 ("Publish") and resource ("shared context object"), and the parenthetical clarifies that this is the project-state document every agent reads, which distinguishes it from the sibling workspace_get_context (the read side) and from workspace_put_file.

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 rather than stated: publishing project state that other agents read first suggests a write to a shared, widely-read slot. There is no explicit guidance on when to use this versus workspace_put_file or workspace_update_capsule, and no mention of overwrite/replace semantics or coordination with workspace_get_context.

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

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

With no annotations, the description carries the full behavioral burden, yet it only discloses the ".." path restriction. It says nothing about overwrite semantics for an existing path, whether parent directories are created, what permissions or agent identity are required, or whether the write is reversible — all critical for a mutation 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?

Two short sentences, front-loaded with the action and followed by the one hard constraint. There is no filler, though the brevity is partly under-specification rather than discipline.

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 three-parameter mutation tool with no annotations, no output schema, and 0% schema coverage needs considerably more explanation than this. An agent cannot tell from the definition whether the call overwrites, what it returns, or how to interpret `agent`.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it constrains the `path` parameter against ".." but says nothing about `agent` (identity? attribution?) or `text` (raw content? encoding? size limits?). Two of three 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?

The description names a specific verb and resource ("Write a shared workspace file") and gives concrete examples of what a file can be (capsule, note, deliverable), which is enough to distinguish this from read-side siblings like workspace_get_file. It does not, however, distinguish itself from workspace_put_context or workspace_update_capsule, which plausibly overlap.

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

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

There is no statement of when to use this tool rather than workspace_update_capsule, workspace_put_context, or workspace_put_file's read counterparts. The only guidance is an implied constraint on the path value, not on 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?

No annotations exist, so the description carries the full burden. It does disclose one real behavioral trait — 'Other sections are preserved' — clarifying partial-update semantics, but it says nothing about authentication requirements for the 'agent'/'token' parameters, whether the 'Decisions (locked)' section can in fact be rewritten, what happens on a missing section or slug, or whether changes are reversible.

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 action and its scope, then the preservation guarantee. Nothing is padded and every clause adds 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 five-parameter mutation tool with no annotations, no output schema, and zero schema descriptions, the definition is too thin: identity/auth parameters, slug semantics, and the outcome of a call are all left unspecified.

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 five parameters. The description only clarifies the 'section' enum values and implies 'text' is the content written, while 'agent', 'token', and 'slug' receive no explanation at all — a significant gap for a tool that mutates shared state.

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 one capsule section') and enumerates the four valid targets (State, Decisions (locked), Next, Session log), so an agent can distinguish it from workspace_get_capsule. It stops short of naming the read sibling explicitly, but the write-versus-read split is obvious.

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

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

The description implies the usage pattern — touch exactly one section per call, or append to Session log — which is useful scoping guidance. It gives no explicit when-to-use versus workspace_get_capsule or workspace_put_context, and no prerequisites or ordering advice.

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