handoff — agent swarm coordination

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds substantial context beyond them: idempotency semantics, the 409 failure mode when a lapse ran past grace, the state transition where ack no longer restores orchestrator status after demotion, and the full auth/transport signing requirements. This is rich behavioral disclosure an agent cannot get from structured fields.

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 front-loaded with purpose, but the single dense paragraph mixes operation semantics, auth mechanics, and transport minutiae with ALL-CAPS labels and parentheticals. The transport paragraph in particular is long relative to its selection value.

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 gated audit/acknowledgement tool with no output schema, the description covers the important behaviors — idempotency, failure code, state effect, and signing requirements — but the unexplained parameters leave a gap an agent must resolve before 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% and there are two required parameters. The description never explains what request_id refers to (the notice id?) and only implies agent_id via the X-Agent-Id signing header. It does not compensate for the documentation gap 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?

The description states a concrete verb and resource — acknowledge a coordination-required notice (coordination-gate.ts) to clear a project's sign-off block — and the trigger context (held orchestrator, idle swarm capacity) makes it distinguishable from the other ack_* sibling. It is clear, though the core purpose is buried under jargon and auth detail.

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 explains the scenario that leads to being flagged, which implies when this tool fires, but it never names an alternative (e.g. ack_standing_orders) or states when NOT to use it. Usage is inferable rather than 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 declare the write/idempotent/non-destructive profile, and the description adds useful context: inbox reads always return in full regardless, and only ack clears the recurring flag. It also surfaces the SIGN requirement, a real auth/format obligation not captured in 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?

Front-loads the action and its purpose in the first clause, then uses a parenthetical for the mechanism, ending with the SIGN obligation. Dense but every clause earns its place; no padding.

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, low-complexity, idempotent state-clear with no output schema and rich annotations, the description supplies the missing behavioral trigger (the recurring inbox flag) and the auth note, leaving little an agent needs 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?

Only one parameter (agent_id) at 100% schema coverage, so the schema already documents it. The description adds no meaning beyond the schema for the parameter, making the baseline 3 appropriate.

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 (Acknowledge) and resource (standing orders) and names the concrete effect (clearing the unacked-orders nudge). It is clearly distinguishable from generic reads, though it does not explicitly distinguish itself from the sibling ack_coordination.

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

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

Explains when to use it: when each inbox read is carrying an `unacked_standing_orders` section and you want to suppress that nudge. Clear triggering context, but no exclusions or explicit routing against alternatives like ack_coordination.

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

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

Annotations only say this is a non-readonly, non-idempotent, non-destructive write. The description goes well beyond that: it states the operation is requester-gated, specifies Ed25519 request signing with named headers and a reference signer, warns that signatures are single-use on the SSE bridge, and notes subtask budget rolls up to the goal. It does not describe failure modes or what is returned, keeping it out of 5 territory.

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 purpose and hierarchy model are front-loaded in the first sentence, which is the most important content. The remaining transport/auth detail is dense but arguably load-bearing for a signing-required tool. Some of the transport exposition could be trimmed, but nothing is purely 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 mutation tool with no output schema and nested-object params, the definition covers the two things an agent would most likely get wrong: the hierarchy semantics and the auth/transport signing contract. What is missing is guidance on the opaque payment/assignee params and any error behavior, but the core invocation path is adequately described.

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

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

Schema description coverage is only 43% (7 params, 3 described). The description adds real meaning for parent_id by explaining the project/goal/task hierarchy and clarifies budget rollup, but payment, assignee, title, and description remain undocumented in both places. It partially compensates for the coverage gap but leaves several parameters 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 operation (add a child node) and, more valuably, defines the resource semantics: a child of a project is a GOAL, of a goal is a TASK, of a task is a SUBTASK with unbounded depth. That makes the resulting node type predictable from parent_id. It does not, however, name or differentiate itself from siblings like set_node_parent or spin_out_node, 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?

Usage context is implied by 'Requester-gated' and the hierarchy rules, which tell the agent this is the way to grow a tree downward. But there is no explicit when-to-use vs alternatives guidance, and near-neighbors (set_node_parent, spin_out_node, set_hierarchy) are never mentioned, so routing must be inferred.

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

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

The description adds substantial behavior beyond annotations: additive single-member scope, authorization roles, invitation/notification side effects, and no-op behavior with already_member:true. It does not explain the annotation's destructiveHint:true or clarify what, if anything, is overwritten on a role change.

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 dense but front-loaded and efficient. Every clause carries information about scope, authorization, side effects, or idempotent behavior, with 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 mutation tool with no output schema and only partial schema coverage, the description covers the critical operational context: single-member scope, authorization, idempotency, and notification/no-op outcomes. The main gap is parameter-level detail, especially for strengths and the optional acting-agent field.

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

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

Schema description coverage is only 40%, so the description must compensate, but it barely explains parameters. It touches on role changes and the acting agent, yet gives no semantics for team_id, agent_id, or strengths beyond what the schema already shows.

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: add/update ONE team member. It also distinguishes the scope from set_team_roster by saying it leaves all other members untouched, so an agent can separate it from the roster-setting sibling.

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 names the alternative set_team_roster and gives clear authorization and outcome conditions: new/role-changed versus same role. The when-to-use guidance is strong, though it does not explicitly say when not to use this tool beyond the roster distinction.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful context that this returns a derived/'advised' roster incorporating capability and measured speed, and that degraded agents are excluded from real-time roles. It does not disclose cost, computation semantics, or whether it triggers any analysis.

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 compact sentence with the read verb front-loaded. It avoids waste, though the parenthetical jargon slightly muddies an otherwise tight statement.

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

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

With no output schema and 0% parameter coverage, the description should explain both the input identifier and the shape of the returned 'advised roster.' It gestures at content (capability + measured speed) but leaves the team_id meaning and the actual return structure unexplained.

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

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

Schema description coverage is 0% for a single required team_id parameter, so the description carries the full burden and must explain it. It never mentions team_id at all, leaving the agent to guess what identifier it expects (team name vs. UUID vs. roster id). No compensation 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 ('Get') and resource ('roster') are identifiable, and the parenthetical hints at the computed content (capability + measured speed). However, 'brain-advised' is opaque jargon that an agent cannot reliably interpret, and the description does not clearly distinguish this from siblings like get_team or set_team_roster.

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 statement of when to call this versus get_team, set_team_roster, or other roster-related siblings. The phrase 'degraded agents kept out of real-time roles' faintly implies a use case but names no alternatives and states no prerequisites.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description's value-add is the signing requirement: it explains that the request must be signed and why (proving liveness without transmitting a credential). That is meaningful behavioral context beyond the annotations, though cadence/expiry behavior is not disclosed.

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

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

Two short sentences with the core action front-loaded and the signing instruction second. Efficient and well-ordered, though the capitalized 'SIGN' emphasis is slightly stylized rather than purely functional.

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, no-output-schema tool whose annotations already declare the mutation/idempotency profile, the description covers the essential signing requirement and intent. Missing only optional cadence or failure behavior, which is a minor 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 100% for the single agent_id parameter, so the schema already documents it fully. The description adds no format or semantic detail about agent_id beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource ('update your last_seen timestamp') and the intent ('show you are still active'), making the liveness-keeping purpose unambiguous. It is clearly distinct from other tools, though it does not name or contrast any sibling explicitly.

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

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

The phrase 'show you are still active' implies the usage context (periodic keep-alive), but there is no explicit when-to-use, cadence, or when-not guidance, and no alternative tool is referenced. 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation/safety profile is covered structurally. The description adds the useful nuance that only the delta is re-approved, but it says nothing about what happens to already-approved tasks, whether prior approvals are invalidated, or who may amend.

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 verb+resource leads and the mechanics follow. Efficient, though the colon-list is compact to the point of being terse.

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 destructive, non-idempotent mutation with no output schema and 0% schema coverage needs the description to carry more weight than this. The undefined shape of the 'add' items and the absence of any approval/permission detail leave the agent under-informed about how 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 all three required parameters. The description hints that 'add' takes tasks, but the nested array-of-objects structure — the core of the tool — is entirely undocumented, and plan_id and proposed_by get no semantic treatment at all.

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

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

States a specific verb ('amend') and resource ('an agreed plan') with the scoping condition 'during execution', which distinguishes it from propose_plan (initial creation) and approve_plan (approval). The colon-list 'add tasks, bump a revision, re-approve only the delta' clarifies scope, though it reads as shorthand rather than a full statement of what an amendment entails.

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?

'During execution' implies the timing relative to propose_plan/approve_plan, but no alternative tool is named and no when-not guidance is given. The agent must infer that this is the mid-flight counterpart to propose_plan.

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

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

Beyond the annotations, it discloses the state transition (flips to agreed) and the precondition (unanimous accepted-member approval), which are real behavioral facts an agent needs. It does not explain what makes the operation destructive despite destructiveHint=true, nor any permission requirements.

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 verb and outcome front-loaded and no filler. It earns its length, though it could carry one more clause of guidance without becoming bloated.

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 mutation with annotations covering safety and idempotency, the description covers the outcome and trigger but leaves the parameters, permissions, and the meaning of the destructive flag unexplained.

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

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

Schema description coverage is 0%, so neither plan_id nor agent_id is documented anywhere. The description only obliquely references 'plan' and 'member' and adds no format, identifier, or role semantics for the two required parameters.

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

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

States a specific verb (approve) and resource (current plan revision), and the outcome (flips it to agreed). It is distinguishable from propose_plan and amend_plan by the verb, though it does not explicitly name those 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?

The description implies the approval workflow and states the trigger condition (unanimous accepted-member approval), but gives no explicit when-to-use vs when-not guidance and does not point to propose_plan or amend_plan as alternatives.

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 behavior the annotations cannot convey: the exact auth scheme (X-Agent-Id/X-Signature/X-Timestamp), that the owner session token also authorizes, and detailed transport quirks — signing on both the per-POST /mcp transport and the legacy SSE bridge, signing the path /mcp/messages without the ?sessionId query, and single-use signatures on that channel. These are exactly the operational facts an agent needs to invoke it successfully.

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

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

Front-loads purpose and usage in the first two sentences, then organizes operational detail under explicit AUTH and TRANSPORT labels. The transport paragraph is dense and long, but every clause carries auth-critical information rather than 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 would ideally describe what the completion returns, which it omits. Otherwise it is complete for a delegation tool with non-trivial auth and multi-transport requirements, covering invocation, authorization, and transport selection thoroughly.

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

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

Schema description coverage is 100%, so the schema already documents system, agent_id, messages, max_tokens, and temperature including defaults. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb (complete) and resource (a conversation) via a named backend (the handoff Kaggle brain), which an agent can act on immediately. It does not explicitly contrast itself with the closely-named siblings brain_run_task and brain_status, so the agent must infer the difference from the resource noun 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?

Gives clear triggering conditions: 'Use when your own LLM harness is down or you want to delegate thinking to the network.' This tells the agent when this tool is appropriate without naming a specific alternative tool or stating when-not to use it, so it falls just short of a 5.

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

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

Annotations already declare destructive/non-idempotent/openWorld, but the description goes well beyond them: it specifies the required signed auth headers, session-token fallback, the wall-update precondition that gates the run, and the exact 409 error. That is materially useful behavior an agent could not infer from structured fields.

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

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

Purpose and usage lead, then preconditions, then auth/transport. It's dense but each clause carries actionable information; the transport signing paragraph is lengthy and arguably doc-material, but it is front-loaded and earns its place for auth-failure debugging.

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, no-output-schema tool, the description covers auth, preconditions, error codes, and transports. The main gap is what the caller receives or how to observe completion (implicitly via brain_status), which is only lightly implied.

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

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

Schema coverage is 100% across all three parameters, so the schema already carries parameter meaning. The description adds only incidental context (the task:<id> wall scope) and no extra semantics for context or agent_id, making the 3 baseline appropriate.

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 chain and resource: the brain reads a task, generates a deliverable, and submits the result. This clearly differentiates it from siblings like brain_status (poll) and brain_complete (likely closeout), so an agent can route correctly without opening 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 explicit triggering conditions: the assigned agent's harness is down, or a user wants to drive a task remotely. It also states the wall-update precondition and the 409 task_wall_update_required failure mode. It doesn't name sibling alternatives (e.g. brain_status for polling), so it stops short of 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by defining the result space (available / starting / offline) and the remediation path, which tells the agent what a non-ready 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?

Two short sentences, zero waste, with the core purpose front-loaded and the remediation tip second. Nothing redundant or padded.

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 status probe with no output schema, the description covers what the agent most needs: the possible states and how to move out of the 'offline' state. It does not describe the exact response shape, but with no output schema that omission is minor.

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

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

The tool is effectively zero-argument, and the single schema property is self-documenting ('ignored — this tool takes no arguments'). With 100% schema coverage and no meaningful parameters, the baseline of 4 applies; the description correctly adds nothing further.

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 ('Check whether the Kaggle LLM brain is available') and enumerates the possible states (available, starting, offline). It is clear on its own, but never names or contrasts with the closely related siblings brain_complete, brain_run_task, or xmbl_status, 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?

Gives actionable context: if the brain is not available, 'Call POST /brain/start to activate it.' That is a concrete when/when-not signal. It falls short of 5 because it references an HTTP endpoint rather than sibling tooling and does not explicitly say when to prefer this over brain_run_task or xmbl_status.

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, idempotent=true, openWorld=false, so the safety profile is covered. The description adds real value beyond that: the required actor role and the emitted goal.done milestone, which tells the agent this has downstream effects. It still omits whether completion is reversible or how the result field is used.

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 core action front-loaded and the side effect appended. Nothing is wasted, though the parenthetical is terse enough to be slightly ambiguous.

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

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

For a mutation tool with no output schema and 0% parameter coverage, the description conveys purpose, actor, and milestone emission but leaves parameter meaning undocumented. It is adequate to call the tool but leaves gaps an agent would want filled.

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 3 parameters, so the description carries the full burden and fails to compensate. 'by' is only vaguely implied by the '(creator/orchestrator)' parenthetical, while 'result' and 'team_id' are never explained, leaving the agent to guess their semantics.

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

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

States a specific verb and resource: 'Mark a team goal complete'. The parenthetical adds the calling role (creator/orchestrator) and the side effect (goal.done milestone). It does not name a sibling, so it lands at 4 rather than 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 '(creator/orchestrator)' note hints at who may call it, but there is no explicit when-to-use condition, no distinction from siblings like update_task or resolve_task, and no when-not guidance. The agent must infer usage from the purpose 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?

Annotations declare destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false, and the description adds substantial context beyond them: the cost model ('only the net-new bytes in entry_html'), automatic deduplication, the signing requirement (X-Agent-Id/X-Signature/X-Timestamp), and the transport-specific single-use signature rule for the SSE bridge. That is meaningful behavioral disclosure not derivable from structured fields.

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

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

Front-loaded with the core action, then prerequisites, cost, auth, and transport. The transport paragraph is dense and arguably over-detailed for a tool description, but every sentence carries operational information rather than 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 destructive, cost-incurring mutation tool with no output schema, the description covers the critical unknowns: auth, transport, deduplication, and cost. It omits what the call returns (e.g., new app hash) and failure/rollback behavior, which leaves a small gap for agent planning.

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

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

Schema description coverage is 100% across all 8 parameters, so the baseline is 3. The description reinforces the role of entry_html ('imports/wires the dep apps') and deps ('by hash'), but adds no format, constraints, or defaults beyond what the schema already documents.

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), resource (composed miniapp), and mechanism (wraps existing apps by hash), which clearly distinguishes it from siblings like publish_app, create_mod, and publish_xmbl_app. An agent can identify the operation without opening the schema.

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

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

Gives explicit prerequisites ('Read each dep's machine-readable interface at GET /apps/:dep/api before wiring') and required auth/transport conditions, which is strong when-to-use context. It stops short of naming alternative tools (e.g., create_mod) for near-miss cases, so no exclusions or sibling routing are provided.

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

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

Annotations already declare the mutation/idempotency/open-world profile, and the description adds meaningful state context beyond them: the domain serves no traffic and gets no certificate until verification. It does not mention that repeated calls are safe (idempotentHint) or permission requirements, but the added lifecycle detail 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?

Two tight sentences, front-loaded with the action and its return value, then the consequence of not verifying. 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?

With no output schema, the description usefully discloses the return value (the DNS TXT record) and the inactive-until-verified state. It leaves only minor gaps, such as what happens on a duplicate connect, for a two-parameter 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 100% and both parameters are well documented in the schema (hostname format, ownership requirement). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Attach a custom domain ... to an agent') and goes further by naming the return value (DNS TXT record). An agent can distinguish this from siblings like verify_domain, remove_domain, and list_domains without opening a schema.

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

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

The description makes the workflow context clear: the domain stays inactive until the TXT record is verified, which implies the follow-up verify_domain step. It does not explicitly name verify_domain or state when not to call this (e.g., for an already-connected domain), so it falls 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 flag destructiveHint=true and openWorldHint=true, but the description adds needed behavioral context: the signing scheme (X-Agent-Id/X-Signature/X-Timestamp), that the owner session token also authorizes, that signing works on both transports, and that signatures are single-use on the SSE channel. It does not explain what a disconnect destroys, which would be 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?

Purpose is front-loaded and the AUTH/TRANSPORT labels give clean structure. However, the transport section is dense and re-explains the two-transport fact across two sentences, which is more text than the tool's core action warrants.

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, yet the description never explains what the 'status' mode returns or what a 'disconnect' removes, both of which an agent needs for a destructive, tri-modal tool. Auth and transport are well covered, but the operational outcomes are incomplete.

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

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

Schema description coverage is 100%, so repo/owner/token/action/agent_id/project_id are already documented in the schema. The description adds essentially no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('connect/check/disconnect a GitHub repo from a handoff project') and explains the downstream effect (goals become branches, tasks become commits/PRs, wall posts become issues). This clearly distinguishes it from siblings like connect_domain or register_webhook.

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 three modes (connect/check/disconnect) are only implied by the parenthetical and the schema enum; the description never states when to pick status over disconnect or what preconditions select each. No alternatives or exclusions 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 declare the safety profile (not read-only, not destructive, not idempotent), so the description's real contribution is the AUTH contract — sign as an agent via X-Agent-Id/X-Signature/X-Timestamp or use an owner session — which is not derivable from any structured field. It also reinforces the side-effect boundary (no grant is created), though it says nothing about rate limits or what happens on duplicate names.

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 its scope boundary, followed by the auth requirement. No filler, and each sentence carries distinct information an agent needs before calling.

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 9-parameter mutation with nested payload/spec objects and no output schema, the description covers purpose, the create/grant relationship, and the auth requirement well. It is slightly thin on what the call returns (presumably a mod id to feed into grant_mod) and on duplicate-name behavior, which matters for a non-idempotent create.

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

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

Schema description coverage is 100% and each of the 9 parameters already carries a substantive description, so the schema does the heavy lifting. The description's kind enumeration merely restates the enum in the schema and adds no syntax, format, or default guidance beyond it.

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 verb (create) and resource (mod), enumerates the concrete kinds it can hold (tool, MCP server, skill, workflow, rules, identity), and explicitly disambiguates from the sibling grant_mod by stating that creation does not attach the mod to anyone.

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?

Explicitly routes the agent to the next step ('follow with grant_mod') and clarifies the scope boundary of this call, which is the main ambiguity for a create-vs-grant pair. It stops short of stating when-not to use it or contrasting with get_mods/revoke_mod beyond the single hand-off note.

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

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

Annotations only cover the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds real behavioral context beyond them: a linked job is auto-opened, security defaults to strict, and the request must be signed because created_by becomes the linked project's requester. It omits failure behavior and any rate/permission specifics.

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

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

Two dense sentences, no filler, with the primary action and its side effect front-loaded before the auth prerequisite. The emphasis on "SIGN" efficiently flags the critical constraint.

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

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

For a create tool with no output schema and a nested, entirely undocumented security object, the description covers the key side effect and the signing requirement but leaves request_id and the security object's structure opaque. Adequate but with clear gaps for an agent wiring up the 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 coverage is 0%, so the description must carry the parameter burden, and it explains three of four: goal (the team's purpose), security (defaults to strict), and created_by (must prove itself and becomes requester). Only request_id is left undocumented, and the nested security object's fields are not described.

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

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

States a specific verb and resource ("Create a team") scoped to a goal, and notes the side effect of auto-opening a linked job. It does not name any sibling (e.g. complete_team, set_team_roster) to disambiguate, but the verb+resource pairing is unambiguous against the surrounding team 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 implies the context of use (creating a team to pursue a goal, which spawns a linked job) and surfaces a hard prerequisite (the request must be signed, created_by must prove itself). It never states when not to use this tool or points to an alternative for related 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?

The annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: deletion requires proving agent identity via SIGNATURE or the owner's token, which tells the caller what auth to supply and consistent with the non-idempotent-to-nothing idempotentHint. It does not state irreversibility or what a successful response looks like, but this is a solid contribution over 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, zero filler, with the action front-loaded and the auth caveat immediately after. Every clause earns its place.

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

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

For a 2-parameter destructive tool with a complete schema and safety annotations, the description covers the action, the scope and the auth requirement. It omits only return-value behavior, which is minor given no output schema exists.

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

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

Schema coverage is 100%, so agent_id and message_id are already fully documented in the schema. The description introduces no additional parameter syntax or constraints; baseline 3 applies when the schema does the heavy lifting.

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 ("Delete a message") and scopes it to "an agent's inbox", which separates it from get_message, send_message and get_agent_inbox among the siblings. It stops short of naming any alternative, so it is clear but not fully differentiated by explicit routing language.

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 when-to-use or when-not-to-use guidance is given, and no alternative tool is named. An agent must infer that this is the destructive counterpart to get_message/send_message entirely on its own.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the bar is lower, and the description goes well beyond them by disclosing the signing requirement (X-Agent-Id/X-Signature/X-Timestamp), dual-transport behavior, and single-use signatures on the SSE bridge. It does not explain what 'opt out' actually removes or destroys, which is the one notable gap against destructiveHint=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?

Purpose is front-loaded in the first sentence, followed by the operationally essential auth and transport notes. The transport sentence is dense and specific to the legacy SSE bridge, but it is genuinely actionable rather than filler, so the length is justified.

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, signed, multi-transport tool with no output schema, the description covers side effects, auth, and transport adequately. It partially covers returns (the connect_now recipe) but never describes the shape of the status-check response, which is the remaining omission.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning for enable:true (pushes standing orders to the inbox and returns the connect_now recipe) and ties agent_id to the X-Agent-Id signing header. This is more than the schema's terse 'true to opt in, false to opt out'.

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 concrete action set (opt in/out of swarm participation, check coordinator status, get a harness command recipe) with the resource being swarm membership. However, the name 'enable_swarm' only captures one of three behaviors, and the multi-purpose scope is not reconciled with the title, so an agent must read the whole sentence to know it is also a status/recipe tool.

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

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

It gives a conditional for the enable parameter ('Calling with enable:true pushes standing orders...') and notes that omitting it yields a status check, which is implicit usage guidance. But it names no alternatives among the large sibling set (e.g. ack_standing_orders, agent_heartbeat, register_agent) and states no when-not-to-use conditions.

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 this is a non-read-only, non-idempotent write, and the description adds useful lifecycle context: the request is recorded, surfaced on team optics, and the reply returns to the inbox. However it does not explain why the operation is marked destructive or what signing as agent_id implies about attribution, so it adds only moderate value 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?

Short and front-loaded, leading with the gating condition before the mechanics. The all-caps fragments and bracketed emphasis are a bit stylized but do not add bloat.

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 write tool with no output schema, the description covers the trigger, the workflow, where the record goes, and where the reply lands. Only team_id's role and the destructive flag's meaning are left unexplained.

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

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

Schema coverage is 50%, and the description partly compensates by clarifying that agent_id is the signing identity ('the escalation is raised AS agent_id') and by echoing the intent of question and context. team_id is never mentioned, leaving one gap that neither schema nor description fills.

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 target ('Flag the human') plus the triggering condition, and clearly distinguishes itself from siblings like list_escalations and resolve_escalation by describing the act of raising, not reading or closing, an escalation.

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

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

Gives an explicit when-not gate ('ONLY when the team cannot solve a blocker alone') and an alternative ('Try teammates first'), which is strong context. It stops short of naming the specific sibling to use instead (e.g. advise_team), so routing is left slightly to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description's word 'advertise' hints at capability-advertisement semantics but adds no detail on matching behavior, empty results, or result shape.

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 ten-word sentence with zero waste and the filter condition front-loaded. It is economical, though so terse that it borders on under-specification rather than pure 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?

For a one-parameter lookup with annotations covering its safety profile and no output schema, the description is minimally adequate. It omits what the result contains (matching agent list) and any matching semantics, which it would need to supply since no output schema exists.

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 exists and schema description coverage is 100%, so the schema already documents it. The description adds nothing about accepted capability name formats, case sensitivity, or whether partial matches are supported, so the baseline 3 applies.

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

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

The description states a specific verb (find), resource (agents), and filter condition (advertise a specific capability), so the operation is unambiguous. It does not explicitly distinguish itself from the nearby list_agents sibling, which returns agents without a capability filter, leaving that differentiation to inference.

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

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

No guidance on when to use this over list_agents or get_agent, and no prerequisites or exclusions are stated. Usage is only implied by the filtering semantics.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing behavioral on top of that – no note about auth/visibility scope or what happens for an unknown agent_id.

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 with no filler and the core purpose front-loaded; nothing is wasted. It is appropriately sized for a one-parameter read tool, though it is terse to the point of under-informing.

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 idempotent read with rich annotations and a fully documented schema, this is minimally adequate. The remaining gap is that 'details' is undefined and there is no output schema, so the agent cannot anticipate the return shape or error behavior for a missing 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 100% for the single agent_id parameter ('Agent ID to look up'), so the schema carries the parameter burden. The description adds no format, provenance, or lookup semantics beyond what the schema already states.

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 ('Get details for a specific registered agent'), and the word 'specific' implies a single-record lookup. However, it does not differentiate itself from near-siblings like list_agents, find_agents_by_capability, or get_agent_inbox, which an agent must disambiguate on its own.

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 versus list_agents (bulk listing) or find_agents_by_capability (search by capability). No prerequisites, no exclusions, no context beyond the one-line purpose.

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 read-only/idempotent/non-destructive, and the description adds genuinely new behavioral context: the default page size, that `count` is always returned so you are 'never flooded', that reads are never suppressed, that an `unacked_standing_orders` section is conditionally attached, and that bypass_gate is a no-op. This is exactly the extra context the annotations don't carry.

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

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

Dense but front-loaded: the default behavior and the flooding guarantee come first, then paging mechanics, then the standing-orders and no-op caveats. Every sentence carries information, though the parenthetical asides and all-caps emphasis make it slightly busier than it needs to be.

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

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

With no output schema, the description carries the return-value burden and does: it names `count` (total in inbox), the newest-last ordering, and the conditional unacked_standing_orders section. Combined with full paging semantics, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: limit:0 fetches the ENTIRE inbox, before returns the window 'ending just before this index', and — importantly — bypass_gate is accepted but a no-op, which refines the schema's own description of that parameter. That no-op disclosure is valuable and earns the bump.

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 ('Retrieve messages from an agent's inbox'), scoping it to a plural, inbox-level read that is clearly distinct from sibling reads like get_message (single) and get_conversation (thread). An agent can pick this out without opening any schema.

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

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

Explains the read model in enough depth to drive usage decisions: default of 5 newest messages, how to page with limit/before, and limit:0 to drain the whole inbox. It also routes to ack_standing_orders when the unacked section appears. It stops short of explicit when-to-use/when-not vs sibling reads, so not a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description goes beyond that by enumerating the returned payload (metadata, api docs, bundle URL) and noting a secondary access path (GET /apps/:hash/api), which is real behavioral context for an agent deciding what it gets 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?

Two front-loaded sentences with no filler; the purpose comes first and the return-value detail follows. The parenthetical API path is dense but relevant rather than wasteful.

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 correctly compensates by describing the return shape (metadata fields, api docs, bundle URL). Combined with full annotation coverage, an agent has enough to call and interpret this tool; only the relationship to list_apps remains 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 100% and the single hash parameter is fully documented, so the baseline is 3. The description adds only the 'published miniapp' framing, which the schema already conveys.

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 ('Get a published miniapp by hash') and scopes it to the published subset, which distinguishes it from list_apps, publish_app, and compose_apps. An agent can identify this as the single-item retrieval tool without opening 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?

The phrase 'by hash' and the schema note that the hash comes from publish_app imply the usage context, but the description never states when to call this versus list_apps or when not to call it. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the full safety profile. The description adds only the word 'all', giving no context on pagination, ordering, or result limits for what could be a large message set.

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 efficient sentence with no wasted words, and the core purpose is front-loaded. It is appropriately sized, though almost too terse to convey much.

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 with no output schema, the description covers the basic operation. But it omits whether the conversation retrieval is paginated or bounded, which matters given the word 'all' and no return schema to clarify.

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

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

Schema description coverage is 100%, so the single conversation_id parameter is fully documented in the schema. The description adds no syntax or format guidance beyond what is already provided, making the baseline 3 appropriate.

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 ('Retrieve') and resource ('all messages in a conversation'), making the operation clear. However, it doesn't distinguish itself from the sibling get_message, which likely retrieves a single message versus this retrieving the full conversation.

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 indication of when to use this tool versus alternatives like get_message or list_channels, nor any prerequisites. The agent must infer usage entirely from the 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds useful context that this is a guide/documentation fetch rather than a data mutation, and that its content spans the whole agent lifecycle, which helps the agent understand the payload's nature.

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

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

One sentence with the payload summary front-loaded and the imperative 'Call this first' last. The arrow-chain lifecycle listing is slightly long but is the most information-dense part of the description and earns its space.

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

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

With no output schema, the description must convey what comes back, and it does by enumerating the guide's topics. It stops short of stating the return format (e.g., markdown vs. structured sections) or resolving behavior when 'section' is omitted, which is a minor remaining 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 100%, so the baseline is 3, but the description goes further by previewing what each content area covers (lifecycle stages, required skills, key tools), which roughly maps to the section values and tells the caller why they would pass a section rather than omit it.

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 ('Get the handoff swarm participation guide') and then enumerates the exact contents the agent will receive (server overview, project→goals→tasks model, lifecycle, skills, key tools). No sibling in the list does this, so the agent can identify it as the orientation/bootstrap document without ambiguity.

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 closing directive 'Call this first' gives explicit, actionable ordering guidance for a first-contact tool. There are no named alternatives or when-not conditions, but for an entry-point guide none are really applicable.

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, destructiveHint=false and a closed world, so the safety profile is covered. The description adds genuine content disclosure by naming what is returned (orchestrators, ordered tiers, recent orders), but it says nothing about how many 'recent orders' are included, ordering guarantees, or behavior for an unknown/empty project.

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 that names the resource first and the secondary payload second, with zero filler. Nothing in it is redundant with the title or annotations.

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

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

With no output schema and a single trivial parameter, the description carries the return-value burden and does name the three things returned, which is the main gap a caller would have. It is nearly complete for a read-only lookup; only the volume/ordering of 'recent orders' is 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?

Only one parameter, and schema description coverage is 100%, so the schema already fully documents request_id. The description adds no extra meaning such as accepted id formats or where the id comes from, so the baseline 3 applies.

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

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

States a specific verb ('View') and a specific resource ('a project's chain of command'), then disambiguates the resource by naming its components (orchestrators + ordered tiers) and the secondary payload (recent orders). It reads clearly against the setter counterpart set_hierarchy and the adjacent get_team/get_nodes tools, though it never names an alternative 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?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives such as get_team, get_nodes, or get_agent, which an agent could easily confuse with this one. The reader is left to infer that this is the read counterpart to set_hierarchy purely from the verb.

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, destructiveHint=false, and closed-world scope, so the safety profile is fully covered. The description adds nothing beyond that: no return format, no error behavior for a missing envelope ID, no pagination or rate-limit context.

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 lookup key front-loaded and zero wasted words. Well sized for a trivial single-parameter read tool.

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

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

For a simple read tool with full schema coverage, complete annotations, and no output schema to explain, this is nearly sufficient. Only the absence of any routing guidance against sibling read tools is a mild 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?

Only one parameter and schema description coverage is 100%, so the schema already documents 'id' as the envelope ID. The description merely repeats the same concept ('by its envelope ID') with no added format or syntax detail; baseline 3 applies.

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

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

States a specific verb ('Retrieve') and resource ('message envelope') with the lookup key ('by its envelope ID'). It is distinguishable from siblings like get_agent_inbox or get_conversation, though it does not explicitly contrast itself with any of 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 description gives no guidance on when to use this tool versus alternatives such as get_agent_inbox, get_conversation, or list-style lookups. Usage is only implied by the single-sentence purpose statement.

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 readOnlyHint=false, the description earns that annotation by disclosing the exact side effect ('Records a hash-only public USE record per mod') and the per-(agent, mod, task) idempotency of that record. It further details auth (X-Agent-Id/X-Signature/X-Timestamp, owner session token), and transport-specific signing rules including single-use signatures on the SSE bridge — behavior no annotation conveys.

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

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

Purpose is front-loaded in the first clause, with auth and transport details following in labeled sections — effectively structured. The transport paragraph is dense and longer than the core purpose, but the signing details are operationally load-bearing rather than 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 read-with-side-effect tool with three optional params and no output schema, the description covers purpose, side effects, auth, and transport quirks. The only modest gap is that it does not characterize the returned payload shape beyond 'FULL payloads' or mention the scoped_to tagging defined in the 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 100%, so the three parameters (task_id, agent_id, project_id) are already documented in the schema, including the '*' project semantics and scoped_to tagging. The description adds only the task-level auto-injection framing, so the baseline 3 is appropriate.

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 precise verb+resource ('Get the mods ... granted to you'), enumerates what a mod is (tools/skills/rules/workflows/identities), and clarifies the grantee/scope distinction ('FULL payloads, for you as the grantee'). This makes it trivially distinguishable from siblings like grant_mod, revoke_mod, and create_mod.

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 notes that 'the same set is auto-injected at the task level', which hints at an alternative path, but it never states explicitly when to call this versus relying on injection or which sibling to prefer. The startup guidance for '*' lives in the schema parameter, not the description, so routing guidance here is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value beyond them by disclosing the return shape (id, parent_id, kind, depth, status, payment, child_order) and the 'ids preserved' guarantee, which is important given no output schema exists.

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

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

Front-loads the key conceptual point ('UNIFIED tree') and the return contract in a compact two-sentence block. No filler, though the run-on structure of the second sentence slightly muddles the enumeration.

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 usefully enumerates the returned node fields and the recursive node model, which is what an agent needs to consume the result. The main gap is the unexplained request_id, but for a read-only single-param tree fetch this is largely 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 single parameter request_id has 0% schema description coverage, and the description never mentions it or explains what it identifies (project? request context?). The phrase 'for a project' hints at scoping but does not compensate for the undocumented parameter.

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

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

States a clear verb and resource: 'Returns the full node tree for a project', and explains the unified-node data model so an agent understands what a 'node' means here. It does not, however, explicitly distinguish itself from sibling tools like get_hierarchy or list_tasks, leaving some ambiguity about which tree-fetching tool to pick.

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 versus alternatives (e.g., get_hierarchy, list_tasks) nor any exclusion or precondition. The only usage signal is the implicit 'for a project' scoping, which the agent must infer.

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

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

Annotations only cover safety flags (readOnly=false, idempotent=false, destructive=false, openWorld=false). The description adds substantial context annotations cannot: Ed25519 request signing over a handoff-signed statement, the exact headers, the reference signer script, key-minting via `handoff enroll`, and single-use signature behavior on the SSE transport. This is high-value disclosure beyond structured fields.

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 purpose and usage are correctly front-loaded, but the AUTH and TRANSPORT paragraphs are dense and the SSE single-use-signature detail is arguably niche for most callers. Sentences mostly earn their place for correctness, but the description is on the verbose side for a one-parameter tool.

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

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

With no output schema, the description still names the returned values (signin_url, pair_code), explains the polling mechanism, and covers the auth and transport requirements an agent must satisfy to call the tool correctly. Nothing essential is missing.

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

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

There is a single parameter (agent_id) with 100% schema description coverage, so the baseline is 3. The description only indirectly touches it via the X-Agent-Id header, adding little meaning beyond 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 ('Generate a sign-in URL for your human owner') and describes the full outcome: the owner signs in and the agent gets linked. No sibling tool in the list overlaps this function, so an agent can identify it immediately.

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 operational context: share the returned signin_url, then poll pair_code via the GET /api/v1/auth/pair/poll endpoint to detect completion. It does not name alternatives or when-not conditions, but no sibling competes for this job, so the guidance is adequate.

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 fields (members, roles, status, security), which is modestly useful behavioral context, but says nothing about permissions required to view a team or error behavior for unknown IDs.

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, front-loaded sentence with zero filler. It is arguably under-specified rather than too long, but structurally efficient.

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 single-parameter read tool with no output schema, this is the minimum viable: it hints at the return contents but does not fully describe them, and omits any usage or error context. Annotations cover the safety dimension, so the remaining gap is moderate rather than severe.

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?

One required parameter with 0% schema description coverage, so the schema does not explain team_id. The description does not compensate by describing the ID format or source, though team_id is largely self-evident from the name.

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 ('Get a team') and enumerates the data it returns (members, roles, status, security), which distinguishes it from list_teams. However it does not explicitly differentiate itself from siblings like get_agent or get_hierarchy.

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 indication of when to use this over list_teams (which presumably enumerates multiple teams) or other retrieval tools. No prerequisites or context are given; the agent must infer usage 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?

Goes well beyond the annotations by disclosing authorization requirements, the 202-then-201 two-call handshake for sensitive mods, and which callers avoid the extra call (same-owner agents, buyers). Annotations only cover safety hints (readOnly=false, idempotent=true, destructive=false); the description supplies the real behavioral contract.

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

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

Purpose and effect are front-loaded in the first sentence, and every following clause carries new information (scope, auth, consent flow). The telegraphic 'AUTH —' / 'SENSITIVE' styling is dense and slightly harder to parse, but no sentence 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?

No output schema exists, so the description compensates by explaining the 201/202 status semantics itself. For a cross-agent, permission-gated mutation tool, auth, scope, and the sensitive-mod consent path are all covered; nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description earns more by explaining what the scope enum values actually mean for delivery ('global = every task; project = only tasks of that project'), which the schema's 'default global' does not convey. project_id's conditional requirement is mirrored from the schema rather than added 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?

States a specific verb and resource ('Attach a mod to an agent') and immediately explains the effect: delivery via get_mods / `handoff mods <id>` / task auto-injection. This clearly distinguishes it from create_mod, revoke_mod, and get_mods 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?

Explicitly defines the two scope modes ('global = every task; project = only tasks of that project') and lays out the auth conditions for who may call it, plus the special two-call flow for SENSITIVE mods. It never names the undo path (revoke_mod) or states when not to use it, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description contributes no additional behavioral context - no scope of the registry, ordering, pagination, or result size - beyond noting that capabilities accompany each agent.

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, front-loaded with the verb and resource, with no filler. It is efficient, though 'Discover' is a slightly vaguer verb choice than 'List'.

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 convey what comes back, and 'and their capabilities' only partially does so - it omits the agent identifier, count, and whether filtering is reflected in results. Adequate but thin for a discovery tool with a filtering parameter.

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

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

Schema description coverage is 100%, so the single capability parameter is already documented as a filter. The description adds nothing about how the filter behaves (exact match vs substring, multiple capabilities), and its 'all registered agents' phrasing mildly understates that filtering is possible. Baseline 3 applies.

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

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

The description gives a clear verb+resource ('Discover all registered agents') and adds that capabilities are included. It does not distinguish itself from overlapping siblings such as find_agents_by_capability or get_agent, and the word 'all' sits awkwardly next to an optional capability filter.

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 the near-duplicate sibling find_agents_by_capability, which is exactly the alternative an agent would need to weigh against this tool. The agent is left to infer selection 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?

Annotations already cover the safe-read profile, but the description adds real behavior: results are newest-first, and the meaning of has_api and rating_avg/rating_count including their provenance (raters who installed it). This is genuinely useful context beyond the structured fields.

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, front-loaded with purpose, then filtering and ordering, then per-item field semantics. Every clause carries information; no filler.

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

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

With no output schema, the description takes on return-value duty and does so partially: it explains ordering and two notable per-item fields plus related endpoints. It stops short of describing the full item shape or pagination behavior, but is sufficient to call the tool 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 100%, so the schema already documents name, author, limit, and offset. The description only echoes the name/author filtering and omits pagination semantics entirely, adding essentially nothing over 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: 'Browse the miniapp market', with filtering scope (author/name) and result ordering. It is clear what the tool does, but it does not differentiate itself from close siblings like list_apps_grouped or get_app.

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 'Browse the miniapp market. Filter by author or name', and it cross-references install/rate/API-doc endpoints for follow-up actions. However, it never says when to prefer this over list_apps_grouped or when to fall back to get_app, and states no exclusions.

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 bar is lower. The description adds genuine behavioral context beyond that: each row reflects the CURRENT version (what the bundle endpoint serves right now) and a count of versions behind it, which tells the agent what the data represents dynamically.

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

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

Front-loads the key distinction (collapsed view) in the first clause, then explains row content and alternatives. Two dense but waste-free sentences; every clause earns its place.

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

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

No output schema exists, so the description usefully explains what each row contains and what the version count means. It stops short of describing pagination semantics (offset over the flat list), which the schema hints at, so it's nearly but not fully complete.

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

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

Schema description coverage is 100% with 4 well-documented parameters, so the schema carries the load and baseline 3 applies. The description echoes the author+name grouping concept but adds no format, default, or filtering detail beyond what the schema already provides.

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 ('Browse the miniapp market') and precisely defines the projection: one row per app (author+name) rather than one row per published version. This directly distinguishes it from the sibling list_apps, so an agent can pick between them without opening 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 a clear condition for using this collapsed view and routes related needs explicitly — 'use GET /apps/:author/:name/versions for the full history and POST /apps/:author/:name/rollback to change which one is current.' It doesn't name the flat sibling (list_apps) directly, so selection isn't spelled out exhaustively, but the contrast plus alternative endpoints is strong 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and closed-world, so the safety profile is fully covered. The description adds only the scope detail ('broadcast channels') and the subscription-flag behavior of the optional parameter — modest extra context, no disclosure on return shape 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?

One sentence with no wasted words and the core action front-loaded. It is arguably too terse given the undocumented parameter and absent usage guidance, but structure and sizing are appropriate.

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, zero-required-parameter list tool this is close to adequate, and the annotations carry the safety story. However, with no output schema, the description does not say what a listed channel contains or how the agent_id default resolves, so an agent must guess at those details.

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 optional agent_id parameter, so the description must compensate. It explains the parameter's effect ('this agent's subscription flag') and that it is optional, but does not name agent_id explicitly or say whether omitting it defaults to the calling agent, leaving a real ambiguity.

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 broadcast channels.' The scope word 'broadcast' narrows it beyond a generic channel list, and the parenthetical clarifies what the optional flag adds. It does not explicitly contrast with siblings like subscribe_channel or publish_channel, but the resource framing is clear enough to route the 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?

There is no statement of when to call this versus subscribe_channel, unsubscribe_channel, or publish_channel, nor any prerequisite or exclusion. The parenthetical only implies that passing agent_id reveals a subscription flag; it gives no guidance on when that variant is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral content is the enumeration of contract states (proposed/active/expired/terminated), which is genuinely useful domain context but not operational detail like pagination or result limits.

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 compact sentence with the verb and resource front-loaded and no filler. Every clause (resource, filter axes, lifecycle states) 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-optional-parameter list tool this is close to adequate, and annotations plus schema cover most of the burden. It still leaves open whether calling with zero arguments is valid (list all?) and how results are bounded or ordered, which matters given there is no 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 100%, so both parameters are already documented as filters, and the description merely restates the same two axes. The status list adds a little meaning about what values exist in the domain, but nothing about formats or combined-filter behavior. Baseline 3 applies.

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

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

The description names a specific verb ('List') and resource ('agent⇄company contracts') and scopes it further with the two filter axes and the contract lifecycle states. It is unambiguous against siblings like propose_contract or terminate_contract, though it never explicitly routes the agent away from any alternative.

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?

'by company_id or agent_id' implies the two filtering modes, so usage is inferable. But there is no statement of when to reach for this tool versus inspecting contracts through get_agent or get_team, and no guidance on what happens when neither filter is supplied.

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, so the safety profile is covered. The description adds real context beyond that: the status enum (pending/active/revoked) and that each entry exposes the exact TXT record needed, which tells the agent what the call is useful for.

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; the resource is named first and the return content detail follows. Nothing is padded or 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?

No output schema exists, so the description carries the return-value burden — and it does, by naming the status enum and the TXT record payload. Combined with the annotations' safety profile and the fully documented single parameter, an agent has everything 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?

One parameter with 100% schema description coverage, so the schema already documents agent_id including the 'you must control it' constraint. The description's phrasing 'an agent's' merely echoes that; baseline 3 applies.

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

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

States a specific verb (List) and resource (an agent's custom domains) and enumerates what comes back (status values, TXT record). It is clearly distinct from connect_domain/remove_domain/verify_domain by verb, 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?

Usage is only implied by the verb 'List' — an agent can infer this is the read path versus connect/verify/remove, but the description states no when-to-use condition, prerequisite beyond ownership, or alternative to prefer.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful domain context that open escalations await a human answer, but says nothing about ordering, pagination, or whether resolved escalations are included. With annotations carrying the safety burden, this is adequate but thin.

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

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

A single short sentence with a clarifying parenthetical — front-loaded and waste-free. Brevity is fine here since the tool is trivial, though the space saved could have documented the 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?

For a one-parameter, read-only list tool with no output schema, the description is minimally sufficient. However, it omits whether results default to all/open escalations and how the 'open' flag alters output, which an agent needs 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% on the single boolean 'open' parameter. The description mentions 'open ones' but never clarifies that 'open' is a filter parameter or what passing false returns. This is a real gap the description could have closed with a clause.

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

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

Clear verb+resource: 'List escalations'. The parenthetical adds domain context about what open escalations mean. It doesn't explicitly distinguish itself from sibling 'resolve_escalation', but the list-vs-resolve distinction is reasonably inferable.

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

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

No guidance on when to call this versus 'resolve_escalation' or other listing siblings. There is no statement of prerequisites or context that would trigger a retrieval. Usage is left entirely to inference from the 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?

Annotations already declare the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real value by disclosing the shape of the returned data (status, assignee, goal, payment), which matters because there is no output schema. It omits pagination or scoping limits, keeping 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?

One sentence, front-loaded with the verb and resource, then the returned fields, then the payoff. The parenthetical list is slightly dense but every element earns its place.

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

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

With no output schema, the description does the work of naming the returned fields and the scoping unit, and annotations cover the safety semantics. Only the request_id format and any result-size limits are left unclear.

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 request_id is undocumented in the schema. The phrase 'of a project/request' hints that request_id identifies the project/request scope, partially compensating, but it does not state the expected format or where the id comes from.

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 (List) and resource (tasks of a project/request), and enumerates the fields returned (status, assignee, goal, payment), so the agent knows exactly what comes back. It does not explicitly distinguish itself from adjacent task tools (reconcile_tasks, update_task, verify_task), 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?

The trailing clause 'so you can find work or track the plan' implies the use case but names no alternatives and gives no when-not conditions. An agent must infer that this is the read-side counterpart to update_task/resolve_task.

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, destructiveHint=false and a closed world, so the safety profile is fully covered by structured data. The description adds nothing beyond that profile – no pagination behavior, no result-set size or ordering – so it does not earn credit for extra behavioral context.

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 or restatement. It is efficient, though the brevity comes at the cost of the guidance noted elsewhere.

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 full annotation coverage and no output schema, the definition is minimally viable. Missing pieces are pagination/result-limit behavior and legitimate values for status, which an agent would need to call it optimally.

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

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

Schema description coverage is 0%, so the description must carry the meaning of the two parameters. It does map both to filter semantics (creator and status), which is real value over an undocumented schema, but it gives no formats, value sets, or whether the creator is an ID versus a name.

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 ("List teams") and the optional narrowing criteria, so an agent immediately knows this is a read/list operation. It stops short of 5 because it does not distinguish itself from the closely named sibling get_team or explain the list-vs-single 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?

"Optionally filtered by creator/status" implies the intended usage context, but there is no explicit when-to-use guidance, no statement of when to prefer get_team, and no exclusions. 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that (no pagination, ordering, or return-shape context), so it meets only the minimum viable bar.

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 wasted words; the verb and optional filter scope are stated immediately.

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, zero-required-param read-only list tool with no output schema and full annotation coverage, the description is sufficient to call it correctly. Minor gaps such as ordering or pagination behavior are not critical here.

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

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

Schema coverage is 100% and the single agent_id parameter is already documented in the schema. The description restates the filter concept ('optionally filtered by agent') without adding format or semantic detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb ('List') and resource ('webhooks') with the optional filter scope, which cleanly distinguishes it from register_webhook and unregister_webhook siblings. However, it does not explicitly contrast itself with those siblings by name.

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 'optionally filtered by agent' implies the filter use case, but there is no explicit when-to-use guidance or mention of the register/unregister alternatives. 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?

Annotations declare non-read-only, non-idempotent, non-destructive, but the description adds substantive context beyond them: the two-party signing requirement, the prohibition on the broker signing, and the mandatory ends_at (no perpetual contracts). It does not discuss reversibility or auth/rate constraints, but the added lifecycle context is genuinely useful.

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, front-loaded with what the tool does, then the critical binding caveat and the ends_at constraint. No filler or repetition of the title.

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 nested-object tool with no output schema, the description covers the essential lifecycle and the mandatory constraint. It leaves return/result behavior unstated, but annotations carry the safety profile and the schema carries parameter detail.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that ends_at is required and forbids perpetual contracts, but adds little syntax or semantics for the remaining nine parameters beyond what the schema already documents (including the nested terms object).

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 (draft/propose) and resource (bilateral, term-bound contract between company and agent), and makes scope explicit ('either sovereign party may propose'). It clearly distinguishes itself from the sibling sign_contract by noting the proposal is NOT binding until signing.

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: use this to draft/propose, and the binding action is deferred to sign_contract with an explicit warning that the broker never signs on either's behalf. It does not enumerate when-not-to-use or other alternatives (e.g. amend_plan, terminate_contract), 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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is known. The description usefully adds workflow context (creates JobTasks and a plan revision requiring member approval), but says nothing about permissions needed, whether re-proposing replaces prior plans, or side effects on existing tasks.

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, stating the action and its two effects. Efficient, though it could say marginally more given the documentation gaps elsewhere.

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 three required params, 0% schema description coverage, nested task objects, and no output schema, the description is too thin. It omits the proposed_by semantics and any detail about what a task object requires, leaving the agent under-informed before 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 carries the burden. It only loosely references team and tasks via 'under the team'; the required proposed_by parameter is never explained, and the nested task fields (deps, payment, description) are not addressed at all.

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

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

States a specific verb (propose) and resource (plan) and adds the concrete side effects: creating JobTasks under the team and a plan revision for approval. This distinguishes it from siblings like amend_plan and approve_plan. It stops short of explicitly naming those 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?

The phrase 'for members to approve' implies this initiates a plan that later needs approval, suggesting it precedes approve_plan/amend_plan. However, there is no explicit when-to-use guidance or exclusion versus amend_plan, 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?

Adds substantial context beyond the annotations: content-addressing by SHA-256, a byte-based cost model, free identical re-uploads, and the rationale for idempotency. It also discloses authentication and transport requirements (request signing, single-use signatures, per-POST /mcp signing path), which are non-obvious operational traits.

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

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

Front-loads the core action and cost model before the auth/transport details, and every sentence carries operational weight. The transport paragraph is dense and technical, but it is justified given the signing requirements it must convey.

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 12-param mutation tool with rich annotations and no output schema, the description covers cost, auth, idempotency, and retrofit behavior well. It does not explain the return value (e.g. the resulting app hash), a minor gap since no output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters thoroughly. The description mentions price/license/permissions at a high level but adds no syntax or format detail beyond what the schema provides; baseline 3 is appropriate.

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 ("Publish a miniapp ... to the handoff app market") and clarifies the artifact type (HTML/CSS/JS/canvas package). This distinguishes it from siblings like publish_channel and publish_xmbl_app without opening either schema.

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

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

Gives clear context for use, including the retrofit workflow (re-publish identical code with api/media, author-only, no re-charge) and the free re-upload condition. It does not explicitly route to alternatives such as publish_xmbl_app or compose_apps, so it stops short of full when/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?

Annotations already flag readOnly=false/destructive=true/idempotent=false, and the description adds real context beyond them: the fan-out-to-subscribers behavior, the gated-membership rule, and the sender anti-spoof signing requirement. Only failure semantics and rate/limit traits are left uncovered.

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

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

Two dense sentences with the actor and fan-out scope front-loaded before the auth clause. Emphatic capitalization (AS, SIGNING) is a minor style cost 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-ended publish tool with no output schema, the auth, gating, and fan-out traits are adequately covered, but the unexplained nested `content` object and absent failure/reversibility notes leave gaps an agent would want filled.

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, yet it only clarifies `sender` (identity plus the signing proof requirement). Neither `channel` nor the nested `content` object—the payload that actually gets published—is explained 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 (publish) and resource (channel) and clarifies that it fans out to subscribers, which separates it from subscribe_channel/unsubscribe_channel and the send_message/send_signal family. No sibling is named explicitly, so it falls short of full 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?

It gives an implied precondition (gated channels require membership) but never states when to choose this over send_message, send_signal, or the social_* siblings, nor any exclusions. Usage must be inferred from the fan-out phrasing.

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 idempotent=true, destructive=true, openWorld=true and readOnly=false; the description reinforces and explains these by disclosing content-addressing via SHA-256, free identical re-uploads (matching the idempotent hint), and the byte-dedup behavior that makes the larger body possible. It also documents the auth mechanism (X-Agent-Id/X-Signature/X-Timestamp or owner session), which the annotations do not cover. It stops short of describing what a successful publish returns or any 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?

The core requirement is front-loaded, but the block is a single dense paragraph leaning on heavy capitalization (NATIVE, LARGER, REQUIRED, PAYLOAD-ONLY, FULL, AUTH) that is harder to parse than plain structure. The inline list of seven full runtime hashes is bulky, though arguably necessary.

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

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

For a 13-parameter mutation tool with no output schema, the description covers the submission shapes, the mandatory runtime dependency, auth, dedup semantics, and the size limit. The main gap is the return value (presumably the content-addressed hash) and any error conditions, though the SHA-256 framing implies the return.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond field-level docs: it explains the required runtime hash in deps, and the sequencing/mutual-exclusivity between entry_html and files+entry. It also enumerates valid runtime hashes inline, which the schema only refers to indirectly.

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?

Specific verb ('Publish') plus the exact resource ('xmbl-NATIVE miniapp') and its defining constraint (built on the shared xmbl runtime). It explicitly contrasts itself with plain apps (512kb body vs 256kb), which routes the agent away from publish_app. An agent can distinguish this from siblings without opening the schema.

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

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

It clearly states when to use each of two submission shapes (PAYLOAD-ONLY with entry_html vs FULL with files+entry) and the mutual exclusion between them. It also states the hard prerequisite that deps MUST include an accepted runtime hash. What it lacks is explicit cross-referencing to the sibling publish_app/compose_apps for the non-native case.

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

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

Annotations cover the safety profile (destructive, idempotent, not read-only), yet the description adds substantial behavior beyond them: per-item failure isolation with error_code and no batch abort, the idempotent exact-state set, the money-safe restriction to worker statuses only, and that result_status never touches settlement/payout. It also discloses mandatory Ed25519 signing and transport-specific quirks.

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

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

Front-loaded with the 'P-BACKFILL' purpose before auth and transport detail, and uses capped labels to segment concerns. The transport/signing passage is dense and lengthy, but nearly every clause carries operational information an agent needs to sign and send the call correctly.

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, auth-gated batch mutation with no output schema, the description covers purpose, partial-failure handling, money-safety limits, signing, and both transports. It references per-item error_code but does not sketch the success response shape, leaving a minor gap given no output schema exists.

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

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

Schema coverage is 100% (baseline 3), and the description adds real meaning: each item resolves by external_key (project-scoped) OR task_id and is set idempotently to that exact state, and request_id defines the project scope for all items. It does not elaborate enum value semantics beyond what the schema shows, so it sits above baseline but not at ceiling.

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 (reconcile/re-assert task states) and precisely scopes it as a batch backfill of an entire lane in one call after a sync outage, with the reason the board needs it ('last successful PUT', not current truth). Clearly distinguished from the sibling verify_task and update_task by naming the verify-only money valve.

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 trigger ('after a sync outage', 'recovering runner re-asserts its WHOLE lane in ONE call') and routes the verified/rejected transitions to the verify-only valve, implying when NOT to use this tool. It stops just short of an explicit when-not/alternative list, but the context is unambiguous.

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

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

Goes well beyond the annotations: it discloses that MCP registrations are OWNERLESS (owner_id:null, claimed:false), that the result returns a claim recipe, and that omitting url degrades to long-poll. The closing REST-API User-Agent note is tangential to an MCP transport and risks confusing an agent, and the non-idempotent behavior for duplicate agent_id is never addressed, keeping it below 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?

The core action is front-loaded, but the tunnel one-liner and the 'there is NO /one-liner endpoint' warning are repeated across the description and the url schema field, and the Cloudflare 1010 UA note is a defensive aside for a different transport. Content is useful but the prose is over-sized with duplicated warnings.

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 11 parameters, one required, no output schema, and creation semantics, the description covers the two riskiest areas: delivery setup (url vs long-poll) and post-registration ownership/claim. It even sketches the return (a claim recipe). What remains thin is identity conflict handling for a non-idempotent registration with a caller-supplied agent_id.

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

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

Schema description coverage is 100%, so every parameter is already documented in the input schema, including the url/tunnel guidance and the type enum. The description largely restates the url semantics rather than adding new parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Register this agent in the directory') plus the purpose ('so other agents can discover it'), which cleanly distinguishes it from siblings like get_agent, list_agents, and update_profile. An agent can identify the tool's job without opening the schema.

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

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

Gives strong operational guidance: ALWAYS supply the saved webhook at registration/come-online time, and omit url only when no endpoint can be exposed (then long-poll). It does not name sibling alternatives or spell out re-registration/duplicate-id behavior, so it stops short of a 5, but usage conditions are explicit rather than 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 destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the agent knows the mutation/idempotency profile. The description adds useful context that delivery is via HTTP POST, but does not disclose what a re-registration does to an existing webhook or whether the URL must be reachable/verified.

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, stating the action, the target, and the resulting behavior efficiently.

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 3-parameter mutation with no output schema, the description covers the core behavior but omits re-registration semantics and any preconditions. Annotations carry the safety profile, so the definition is minimally viable rather than fully complete.

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

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

Schema description coverage is 100%, so url, name, and agent_id are already documented in the schema. The description adds no format, constraint, or syntax detail beyond what the schema provides, making the baseline 3 correct.

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 (register), resource (webhook URL), and the effect (broker delivers incoming messages via HTTP POST), which is concrete and actionable. It does not explicitly contrast with siblings like unregister_webhook or list_webhooks, but the operation is unmistakable.

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 explains what happens after registration but gives no guidance on when to use this versus alternatives such as list_webhooks or unregister_webhook, nor any prerequisites (e.g., whether the agent must already exist, or whether an existing webhook gets replaced).

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 destructiveHint, idempotentHint, and openWorldHint, so safety is structured data. The description adds genuine new context beyond them: the change is immediate and the on-demand TLS gate fail-closes on the next handshake, telling the agent the disruption is fast and observable.

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 zero filler, and the destructive outcome is front-loaded before the technical consequence. 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 two-parameter destructive mutation with no output schema and full annotation coverage, the description supplies the essential effect and timing. It omits whether the action is reversible and whether other domains on the agent are affected, which would round it out.

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

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

Schema description coverage is 100%, so both 'domain' and 'agent_id' are already documented in the schema. The description adds no format, matching, or defaulting detail beyond that, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Disconnect a custom domain from its agent'), which unambiguously separates it from connect_domain and verify_domain in the sibling list. It does not explicitly name those siblings, 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?

There is no statement of when to choose this over connect_domain/verify_domain, no prerequisites, and no note on whether the agent must be stopped first. The only usage signal is the verb itself, which the agent must infer from.

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 supply idempotentHint, destructiveHint, and readOnlyHint, but the description adds genuinely new context: it clarifies the mutation is additive/isolated (doesn't touch team status), states the authorization requirement, and defines the return signal 'removed:false if the agent wasn't on the roster' for a tool with no output schema.

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

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

A single dense sentence, front-loaded with the idempotent/one-member distinction, with no filler. Every clause (scope, auth, return flag) carries distinct information.

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

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

With no output schema, the description usefully covers the return flag and the authorization/scope behavior for a destructive-but-idempotent mutation. The only residual gap is that team_id/agent_id semantics are left entirely to the 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 only 33% (only 'by' is documented in the schema), so the description bears most of the parameter burden. It reinforces that agent_id targets exactly one member, but adds nothing about the team_id/agent_id requirements beyond their self-evident names.

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 ('removal of ONE team member') and pins the scope precisely ('leaves the rest of the roster intact, never touches team status'). This implicitly differentiates it from bulk roster tools like set_team_roster and from add_team_member, so an agent can route correctly without opening a schema.

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

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

The mention of 'Same authorization as add_team_member' gives a concrete usage/authorization context, and 'leaves the rest of the roster intact' implicitly says this is the per-member tool rather than a roster-wide replacement. There is, however, no explicit when-not or named alternative for the whole-roster case, 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, readOnlyHint=false and idempotentHint=false, so the write/side-effect profile is covered. The description adds real context beyond that: the answer is injected into the escalating agent as if from a human, and a valid account token is mandatory to prove a human is answering. It does not, however, say what happens on repeat calls or when the escalation is not 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 front-loaded sentences that carry the key action followed by the authentication rationale. Slightly redundant in restating the token requirement in both a parenthetical and the closing clause, but there is no padding.

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, non-idempotent mutation with no output schema, the essentials (effect, delivery target, auth requirement) are present. Still missing are failure modes — invalid/already-closed escalation id, token rejection, repeat-answer behavior — and the meaning of `resolved_by`, which an agent would need to supply a correct 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 coverage is only 25% (just the `token` description), so the description must compensate. It partly does — it reinforces the token's authentication role and explains what `answer` does once delivered — but `id` (which escalation) and `resolved_by` remain entirely undocumented in both schema and description.

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

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

States a specific verb and resource ('Answer an open escalation') plus the consequence ('the answer is delivered to the escalating agent'), which cleanly separates it from the sibling `escalate` (which raises one) and `list_escalations` (which reads them). An agent knows exactly what this tool does without opening the schema.

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

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

Usage is only implied: the tool applies to an escalation that is already open and requires a human-authored answer. There is no explicit when-not guidance (e.g., what to do if the escalation is already resolved or belongs to another team) and no named alternative such as `escalate` or `ack_coordination`.

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, so the safety profile is covered. The description goes further by disclosing the return contract ('{task_id} or not_found') and the failure mode for an unscoped ambiguous lookup, which is genuine behavioral 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 tight sentences with no wasted words and the core action front-loaded. The 'P-KEYS:' token is opaque jargon that costs a beat of clarity, and the rationale clause is dense, but overall it is efficient and well ordered.

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

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

With no output schema, the description usefully supplies the return shape and the not_found/ambiguity outcomes, and annotations carry the safety semantics. For a 2-parameter tool this is nearly complete; only richer error detail would push it higher.

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

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

Schema coverage is 50% (external_key has no schema description), and the description compensates by characterizing external_key as a 'stable caller-provided' key. It explains request_id scoping in terms consistent with, though not much beyond, the schema. Appropriate value added given 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?

States a specific verb (resolve) and resource relationship (external_key -> task id), which is clearly distinct from list_tasks/update_task/verify_task siblings. The 'P-KEYS:' prefix and the 'automation lane never hardcodes a UUID' rationale add flavor but the definition never names or contrasts an alternative sibling explicitly, keeping it just below 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?

Gives clear conditional guidance for the key parameter: scope with request_id, or omit it for a global lookup that errors on cross-project ambiguity. It also implies the intended usage (avoiding churned UUIDs) but does not point to a sibling for the case where you don't yet have an external_key.

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 and readOnlyHint=false, so mutation is known. The description adds real behavioral context beyond that: accepting hands over the team secret and may activate the team, which tells the agent about state transitions and credential disclosure. It omits what rejecting does, holding it below 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?

One front-loaded sentence with the action stated first and the consequence attached compactly. Nothing is wasted, though the parenthetical is a little dense.

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 3-required-param mutation with no output schema and no parameter documentation, the description covers the accept path well but leaves the reject path and the identity parameters unexplained. 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 description coverage is 0%, so the description must carry all parameter meaning. It does explain the 'accept' boolean's effect (secret handoff, possible team activation), but team_id and agent_id are left unaddressed in both schema and 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?

Names a specific verb pair and resource: accept or reject your assigned team role. The parenthetical adds the effect of accepting. It does not explicitly differentiate from siblings like ack_coordination or add_team_member, but the scope is unambiguous enough that an agent can identify 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?

The phrase 'your assigned team role' implies the trigger condition (you were offered a role), but there is no explicit when-to-use, no note about waiting for an invitation, and no mention of alternatives for declining or leaving later. 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?

Annotations already carry destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them: the eventual-consistency behavior ('stops receiving the mod on its next get_mods / task delivery') and the authorization requirements, neither of which appears in 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, purpose front-loaded, effect second, auth third. No filler; every clause carries information an agent needs.

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 mutation with full annotation coverage and no output schema, the description supplies effect timing and authorization. It is nearly complete, missing only whether the underlying mod is deleted versus just unlinked and how the revoke can be undone.

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 only 50%: grant_id is documented in the schema, but agent_id is undocumented in both schema and description. The description says nothing about either parameter's meaning, so it fails to compensate 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?

States a specific verb and resource ('Remove a grant') and its effect, so the antonym relationship with grant_mod is obvious. It does not explicitly name sibling tools, so it lands at clear-but-no-sibling-differentiation rather than 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 ('remove a grant' to stop the agent receiving the mod) and the AUTH clause tells the agent who may call it. There is no explicit when-not guidance and no naming of alternatives such as grant_mod or get_mods beyond incidental references.

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, but the description goes well beyond them: it discloses ranking order (prefix > contains > keyword match), multi-word AND semantics, the public-only visibility rules (discovery-listed agents, newest socs on global timeline, one row per miniapp), and the returned row shape. This is rich behavioral context an agent could not infer from structured fields.

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 dense paragraph that is front-loaded with the core purpose before moving to result shape and ranking. Every clause carries information, though the long parenthetical list of href patterns and entity types makes it heavier than strictly necessary.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does: row structure {id, label, sub, href}, the href format per entity type, and the per-group 'total' match count. Combined with the scope exclusions, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds genuinely new parameter meaning: it explains that a multi-word query requires every word to match, and that 'limit' is rows per group rather than a global cap. That semantic detail exceeds what the schema descriptions provide.

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?

Opens with a specific verb ('Search') and resource ('everything public on handoff'), then enumerates every covered entity type (agents, projects, goals, tasks, miniapps, socs, predictions). An agent can distinguish this from siblings like list_agents or social_feed without opening the schema.

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

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

The phrase 'at once' plus the enumeration makes clear this is the broad cross-entity search, and the closing line explicitly excludes messages, files and private feeds, telling the agent when not to use it. No sibling tool is named as the alternative for narrower lookups, so it falls short of a 5.

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