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

No annotations are provided, so the description carries the full behavioral burden. It implies a write/persist operation but says nothing about whether it requires an api_key, whether items persist across runs, how priority affects pickup, or what happens on failure. For a mutation-style tool with zero annotation coverage this is a significant gap.

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

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

A single tight sentence with the action front-loaded and no wasted words. It is concise, though brevity here edges toward under-specification given the schema it must support.

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 seven-parameter tool with no annotations, no output schema, and no parameter descriptions needs strong textual support, yet the description covers none of the parameters and no behavioral or return context. It is not sufficient for an agent 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?

Seven parameters (agent, api_key, project, priority, source_id, task_type, text) at 0% schema description coverage, and the description explains none of them. The role of api_key, source_id, task_type, and default priority is left entirely undefined, so the description does not 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 (record) and resource (unfinished item), plus the downstream effect (another agent or next recurring run picks it up). It does not name or distinguish itself from closely related siblings such as handoff, pickup, resume, or claim_subtask, 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 description hints at intent (unfinished work to be picked up later) but gives no explicit when-to-use guidance, no exclusions, and does not point to alternative siblings like handoff, pickup, or board_add for the same need. An agent has to guess which tool fits.

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

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

No annotations are provided, so the description carries the full burden. It establishes the tool as read-oriented ('Read it') and clarifies the meaning of the board state, but says nothing about pagination, the max_tokens budget, permissions, or the shape of the returned content.

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 resource definition and the key usage instruction last, with no filler sentences. The phrasing is dense and slightly run-on, but 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 4-parameter tool with no output schema and no annotations, the description covers the concept and the status/path semantics but omits the project filter and the token budget. It is adequate but leaves real gaps an agent must guess at.

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

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

Schema coverage is 0%, so the description must compensate. It documents two of four parameters well: path with an example ('ui/dashboard') and status with enum values ('open|done|dropped|all') that the schema lacks. It says nothing about 'project' or 'max_tokens', so half the parameters remain 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 states what the artifact is ('the project board') and enumerates its contents (asks, targets with goal/current, expectations, actions, deliverables) and implies the read action via 'Read it before working.' It distinguishes itself from board_add/board_update by being the read side, though it never states that verb explicitly as the tool's function.

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 explicit timing guidance: 'Read it before working and before you stop,' plus the rationale that everything open is still owed to the user. It does not, however, name the write siblings (board_add/board_update) as the alternatives when the agent needs to modify rather than read.

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

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

No annotations are provided, so the description carries the full burden. It does disclose one genuine behavioral trait — re-adding an open ask returns repeated=true, signalling the user repeated themselves — which is useful runtime context. However, it says nothing about the api_key parameter, authentication requirements, persistence, or side effects of a write operation.

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 summary sentence is front-loaded and the pipe-delimited kind list is compact and information-dense. The prose is terse rather than bloated, though the pipe formatting makes it slightly awkward to parse.

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-parameter write tool with no annotations and no output schema, the description covers the semantically important fields and the repeated=true return behavior. It still omits auth/credential handling (api_key) and several less-common parameters, so an agent cannot call it fully blind.

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 12 parameters, so the description must compensate. It explains kind (five values that are effectively an undocumented enum), goal, metric, parent, text, and evidence implicitly. It leaves path, agent, status, api_key, current, project, and the kind-specific pairing rules undocumented.

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

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

Opens with a specific verb+resource: 'Record on the project board.' The kind enumeration clarifies what record types exist. It does not explicitly distinguish itself from the sibling 'board_update' or 'board', leaving some ambiguity about add vs. update.

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?

Strong procedural guidance: record every ask VERBATIM before starting, use action for steps, delivered requires evidence, parent links to the ask it serves. This tells the agent when each kind applies. It stops short of naming the alternative tool (board_update) for modifying existing entries.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the status vocabulary, the evidence prerequisites for terminal states, and two important guard rails around asks (non-editable, cannot complete with open children). It omits auth requirements (an api_key parameter exists) and what happens on an invalid transition, but the disclosed rules are substantive and non-obvious.

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 dense sentences, front-loaded with the action and status enum before the conditional rules. No filler. The phrase 'a new measured `current` for a target' is slightly cryptic, but overall the structure is 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 an 8-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers the highest-value semantics (status, evidence, ask constraints) but leaves several parameters and any permission/return behavior unaddressed. Adequate to call it correctly in common cases, incomplete at the margins.

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

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

Schema coverage is 0%, so the description must compensate. It successfully explains status (with the enum values the schema lacks), current (a new measured value for a target), and evidence (with per-status content requirements). However, goal, path, agent, api_key, and id remain completely unexplained in both schema and description, leaving half the 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?

States a specific verb and resource ('Move a board item') and then enumerates the valid status values (open|doing|blocked|done|dropped), so an agent immediately knows this mutates a board item's state. It does not explicitly name the sibling to use instead (board_add) for creation, so it falls just short of full sibling differentiation.

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

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

Provides concrete conditional rules: done requires evidence (commit, file, benchmark, item id, URL), dropped requires a reason in evidence, asks cannot be edited, and an ask cannot be done while child items are open. These are real when/when-not constraints, though no alternatives (e.g. board_add for new items) 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that arbitrary/unlisted tools can be invoked, but says nothing about behavior on an unknown tool name, permission/credential requirements, or whether the inner call's side effects and errors are surfaced unchanged — real gaps for a dispatcher that can perform writes.

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

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

Three short sentences, front-loaded with what the tool does, followed by discovery guidance and a concrete example. No filler; every sentence earns its place.

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

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

For a two-parameter meta-tool with no output schema, the description covers purpose, discovery, and argument shape. Missing only edge-case behavior (unknown tool, nested dispatch, error propagation), which an agent could reasonably want before relying on it.

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

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

Schema coverage is 0% and both parameters are bare, but the description compensates: the worked example shows `tool` is a name string and `args` is a JSON object mirroring the target tool's arguments, and it points to tools(query) for discovering valid names and argument shapes.

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: 'Run any Commons tool by name'. It also distinguishes itself from the 30+ concrete siblings by explaining it is the generic dispatcher that reaches tools the client doesn't even list, so an agent can tell it apart 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?

Explicitly names the discovery path ('Find names and arguments with tools(query)') and the condition that selects this tool (target tool not listed by the client). It stops short of saying when NOT to use it, e.g. prefer calling a listed sibling directly, which is left implicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return packet shape (dependency results and user preferences), the null result when nothing is ready, and the lease/heartbeat constraint. It omits auth expectations and concurrency/failure behavior, but the key operational traits are present.

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

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

The three sentences are tightly front-loaded: purpose first, then return shape, then lease/null behavior. There is no filler and each sentence adds useful 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?

No output schema or annotations exist, so the description must be relatively self-sufficient. It explains the return packet and null case, but the 0% parameter coverage and missing auth details leave gaps an agent would need filled elsewhere.

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 four parameters exist, so the description should compensate more. It hints that subtask_id is optional and implies lease_seconds via the heartbeat sentence, but it says nothing meaningful about agent or api_key, leaving half the parameters unexplained.

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

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

The description uses a specific verb ("claim") and resource ("subtask") and clarifies the two modes: next ready subtask or a specific one. It does not explicitly distinguish itself from nearby siblings like pickup or start_work, but the core purpose is clear.

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

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

It gives an implicit usage cue ("claim the next ready subtask... or a specific one") and mentions heartbeat timing, but it does not state when to choose this over alternatives such as pickup or start_work, nor when not to use it.

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

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

With no annotations, the description carries the burden and delivers real behavioral facts: artifacts land in /jobs/<job>/<key>/, success=false triggers a retry, and gate tasks require approve|reject. Missing auth/permission expectations and return behavior, so not a 5.

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

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

Dense but front-loaded: the core action and the payload rule arrive first, edge cases (gate tasks, leftovers, success semantics) after. Sentence-per-line structure aids scanning, though a couple of clauses are compressed 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?

For a 16-param mutation tool with no annotations and no output schema, the description covers the crucial workflow behavior (artifact storage, retry semantics, verdict handling). The remaining gap is the metadata params, which are largely self-evident from their names.

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 16 params, so the description must compensate. It explains the meaningful ones (repo, branch, commit, diff, verdict, leftovers, preferences, success) but leaves subtask_id, result, agent, model, cost, tokens, tokens_in, and api_key undocumented.

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

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

States a specific verb and resource ('Finish a claimed subtask'), and the workflow framing ('claimed') implicitly contrasts with claim_subtask and submit_task. It never names a sibling outright, so it stays at a 4 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?

Provides conditional routing guidance: pass repo/branch/commit/diff when code changed, verdict for gate tasks, leftovers/preferences for their specific payloads. The success=false rule is an explicit when-to-use boundary. No explicit alternative-tool routing, 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?

With no annotations, the description carries the full behavioral burden, and it delivers the single most important property: this exposes credential metadata only, never secret values. That implicitly signals a safe read operation and prevents an agent from expecting a key it can use directly. It omits return ordering, empty-vault behavior, and error conditions, so it is not exhaustive, but the security-critical disclosure is present.

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

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

Two sentences, both earning their place: the first defines the payload and its boundary, the second gives the action instruction and the safety rule. The non-obvious constraint ('never values') is embedded in the first sentence where an agent will actually read it.

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 parameterless lookup with no output schema, the description tells the agent what comes back (names, services, destinations) and what never does (values), which is the substantive part of the return contract. It leaves the concrete response shape unspecified, but the essential semantics are covered.

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

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

The tool takes no parameters, so there is nothing to disambiguate and the schema (trivially 100% covered) is empty. The baseline for a zero-parameter tool is 4, and nothing in the description is misleading about inputs.

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

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

The description defines the resource precisely: the user's API keys held by Commons, returning names, services, and allowed destinations but never values. This is clear enough to distinguish it from sibling tools, and it explicitly names use_credential as the companion action. It stops short of a clean action verb (it reads as a noun phrase, not 'list credentials'), which is the only thing keeping it from a 5.

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

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

It gives an explicit next step ('Use one with use_credential') and a hard rule ('never ask the user to paste a key'), which tells the agent both why to call this tool and what to do with the result. It does not spell out when it is unnecessary to call it, but for a zero-argument lookup the routing guidance is strong.

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

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

With no annotations, the description carries the full burden: it discloses the id taxonomy and that depth>0 adds graph edges (a real behavioral trait, not repeated anywhere else). It remains silent on read-only vs mutation semantics, error behavior for bad ids, rate limits, and what 'full record' returns.

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

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

Two short sentences, front-loaded with the core action and followed by the one non-obvious parameter behavior. Nothing is padded, though the extreme terseness leaves known gaps (max_tokens, id provenance) unaddressed.

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 annotations, no output schema, and 0% schema coverage mean this thin description is the only documentation. It covers enough to make the call correctly (id required, depth optional) but omits what the record contains, how ids are obtained, and the role of max_tokens.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for two of three params: id (which entity kinds are accepted) and depth (non-zero pulls graph edges). The third param, max_tokens, is never mentioned despite controlling output size.

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

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

The description gives a specific verb+resource ('Fetch the full record for any id') and enumerates the accepted id kinds (memory, decision, entity, session, task, agent), which disambiguates the vague name 'expand'. It does not explicitly contrast itself with siblings like search, why, or board, so sibling differentiation is only implied.

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?

'Fetch the full record for any id' implies this is a follow-up to a listing/search tool that returns ids, and the depth clause hints at when to request graph edges. However, no alternative tool is named and no explicit when/when-not condition is stated, so usage is inferred rather than guided.

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

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

With no annotations, the description carries full burden. It usefully discloses persistence ('kept with the claim (/work/<claim>/)') and downstream consumption ('what the next agent is shown'), which are real behavioral facts. It omits auth/permission needs (api_key) and any notion of reversibility or side effects on other claims.

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 scope, then payload guidance. Four compact clauses with little waste; the parenthetical about /work/<claim>/ is slightly awkward but earns its place by explaining retention.

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-param, mutation-style tool with no annotations and no output schema, the description covers the lifecycle and most payload fields but leaves two parameters (api_key, agent) undocumented and says nothing about authorization or error behavior.

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

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

9 parameters with 0% schema coverage, so the description must compensate. It gives meaning for result, status (enumerating done|dropped, which the schema lacks), claim_id (empty = all open claims), and the code-artifact fields (repo, branch, commit, diff). It leaves api_key and agent completely unexplained.

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

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

Specific verb (close) + resource (work claim) with scope qualification (all open ones when claim_id is empty). This clearly distinguishes it from the sibling start_work and the subtask/claim lifecycle 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?

Explains the triggering condition (closing a work claim), what to supply as the result, the allowed status values, and when to attach code identifiers. It does not name an alternative tool or state exclusions, so it stops short of a 5.

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

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

With no annotations, the description carries the full load and it does disclose several non-obvious behaviors: session_id auto-resolution (latest active session or a new one), that next steps/open questions become 'leftovers', that to_agent posts a task to an inbox, and that Commons verifies the commit on GitHub. Gaps remain around authentication (api_key) and error/failure behavior, but the side-effect disclosure is unusually 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?

Dense but front-loaded: the core purpose leads, followed by conditional details in a logical order, with no filler sentences. Some internal jargon (resume(), leftovers) assumes ecosystem familiarity but is not 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 15-parameter tool with 0% schema coverage, no annotations, and no output schema, the description is reasonably complete on fields and side effects. It still leaves auth expectations, which fields are actually needed (0 required is ambiguous), and the response shape unaddressed, so an agent must guess on some points.

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

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

Schema description coverage is 0%, so the description must compensate and it does explain most parameters: summary, state, decisions, next_steps, open_questions, relevant_ids, repo (owner/name format), branch, commit, session_id, project, and to_agent. It leaves `goal`, `agent`, and especially `api_key` unexplained, so it partially but not fully covers the 15 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 and resource ('Write a structured handoff packet') and enumerates its contents, making its function unmistakable. It also names the counterpart tool (resume()) that consumes the output, so an agent can place it in the workflow 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?

Provides some conditional guidance ('Code work: pass repo...', session_id optional resolution, to_agent posting a task), which implies when the tool applies. However, it never states explicitly when to choose handoff over overlapping siblings like finish_work, record_decision, add_leftover, or submit_task, leaving the routing decision 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?

No annotations are provided, so the description carries full behavioral burden. It conveys that lease state is mutated, but says nothing about permissions/auth, what happens if the lease already expired, whether the operation is idempotent, or what the response contains.

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 immediately. It is efficient, though arguably too terse for a 4-parameter tool with zero schema documentation.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description is thin: it omits auth requirements, lease semantics (default 900s), required parameters, and failure modes. An agent would be guessing at much of the invocation contract.

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

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

Schema coverage is 0% across 4 parameters, so the description must compensate. It implicitly maps to subtask_id and lease_seconds (the lease being extended), but leaves 'agent' and 'api_key' unexplained and adds no format or constraint detail 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 ('Extend the lease on a subtask'), so the agent knows this is a lease-renewal operation rather than a task state transition. It does not explicitly contrast itself with siblings like claim_subtask, pickup, or start_work, 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?

'on a subtask you are working on' implies the usage context (call it while actively working to keep the lease alive), but gives no explicit when-to-use, when-not, cadence, or alternatives. Usage is inferred rather than stated.

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

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

With no annotations, the description carries the full behavioral burden. It does add useful context beyond a bare label: results are read-oriented, credentials are returned as names only (a security-relevant disclosure), and each fact carries its provenance. It does not mention authentication (despite an api_key parameter), read-only guarantees, or rate/scale limits, so the safety profile is only partially covered.

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 scope are front-loaded in the first sentence, followed by a compact pattern of usage examples. It is dense but every clause adds information; the "(names only)" aside and the provenance clause earn their place. Slightly long, but no filler sentences.

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

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

For a complex, argument-flexible tool with no output schema and no annotations, the description explains the shape of what comes back well (tree vs. single item with runs-on/exposes/stores/talks-to). It is silent on how the agent/api_key authentication works and on query syntax details, so an agent calling it can guess the return but not fully understand required invocation context.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate and largely does not. It conveys what the query parameter accepts by example (a name, an LXC id, an IP) but never names the parameter, and the agent and api_key parameters are entirely unaddressed in both schema and description, leaving invocation semantics incomplete.

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 concrete resource (the infrastructure map) and enumerates exactly what it covers — machines, LXCs/VMs, containers, services, domains, tunnels, storage, repos, credential names. An agent immediately knows this is a topology/relationship lookup rather than a messaging or coordination tool. It stops short of naming a sibling it is distinct from, but no sibling in the list overlaps with it, so differentiation is implicit rather than stated.

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

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

It gives explicit call patterns — infra() for the whole tree versus infra("plex"), infra("LXC 106"), infra("192.168.50.205") for a single item — which is real usage guidance. However it never states when to prefer the single-item form over the full tree, nor any alternative tool to use instead, so usage is implied by example rather than framed as a decision rule.

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

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

With no annotations, the description carries the full burden and does real work: it discloses an authorization constraint ('Only the sender and recipients can read a message') and the fact that the tool surfaces real sender identity and origin provenance. It stops short of stating what happens on unauthorized access or the return 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?

Three tight sentences, front-loaded with the action and purpose; parenthetical examples add clarity without padding. Every sentence contributes, though the access-restriction line could sit closer to the action.

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?

Purpose, motivation, and access constraints are covered, and no output schema or annotations exist to relieve the description. However, for a 3-parameter tool with zero schema documentation, the description is incomplete on how to actually supply the message identifier and connection credentials.

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

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

The tool has 3 parameters at 0% schema description coverage, and the description never mentions 'id', 'agent', or 'api_key' or clarifies that 'id' identifies the message to re-read. With the schema contributing nothing, the description 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+resource (re-read one message) and scopes it clearly ('over your own connection'), with an explicit rationale (verify pasted/relayed text before acting). It implicitly separates itself from msg_recv/msg_send by emphasizing re-reading a single known message, but never names a sibling outright.

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

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

Gives a concrete when-to-use trigger: checking text pasted into the prompt or relayed (a wake-up, a forwarded note) before acting on it. Clear situational context, but it names no alternative tool or a when-not-to-use 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?

With no annotations, the description carries the full behavioral burden, and it does disclose two valuable traits: at-least-once delivery (implying possible duplicates/idempotency needs) and the long-poll cap of 60 seconds. It omits other key behaviors such as what limit/types filtering does, whether the ack parameter auto-acks, or whether an api_key is required, so the disclosure is partial.

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 fragments, each front-loaded with the highest-value fact (what you get, the polling cap, the ack obligation). No filler, though the extreme terseness leaves little room for the missing parameter guidance.

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

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

For a 6-parameter tool with zero schema coverage, no annotations, and no output schema, this is under-specified: the ack workflow, limit/types filtering, and auth are all left to guesswork. The delivery-semantics note is valuable but far from sufficient to call this tool confidently.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and it only covers one: wait, with its <=60 ceiling. The ack, agent, limit, types, and api_key parameters receive no explanation at all, leaving most of the calling surface undocumented.

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

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

Names a specific verb and resource ('Your unacked messages') and immediately characterizes the delivery model as at-least-once, which tells the agent exactly what this returns. It does not explicitly differentiate from the close sibling msg_get, so the agent has to infer the boundary between 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 workflow instruction 'Ack with msg_ack after handling' gives a clear follow-up action and names the sibling to use next. However it never states when to choose msg_recv over msg_get (the obvious alternative), leaving the core selection decision 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: task becomes a tracked job, routing to a live agent, reroute=false to disable, splitting a big task across the team, result returned, and reply showing Commons' knowledge. It omits auth/thread/threading semantics but covers the key side effects well.

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 and target semantics, then layered detail on type and routing. Dense but every clause adds information; no filler.

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

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

For a 10-parameter tool with no annotations and no output schema, the description leaves the majority of parameters unexplained and says little about the body format or threading. The behavioral notes are good but insufficient 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 0% for 10 parameters, so the description must compensate but only explains three (to, type, reroute). Critical params (agent, thread, api_key, project, subject, reply_to) are undocumented in both the schema and the description.

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

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

The description opens with a specific verb and resource: 'Message one agent (to=name) or all (to="*")', immediately clarifying the target scope. It clearly distinguishes its behavior from the receiving counterpart msg_recv, though it doesn't name siblings explicitly.

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

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

It enumerates the type values (message|task|question|review|fyi) and explains what task does, which implies when each mode applies, but there is no explicit 'use this instead of X' routing or when-not guidance. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden. It does disclose one genuinely useful trait not present in the schema: that repeated observations reinforce confidence. It fails to cover whether this requires auth (an api_key param exists), whether re-observation creates duplicates or merges, or how confidence interacts with repeats.

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 core purpose followed by the reinforcement behavior. No wasted words, though the sparseness is arguably under-specification rather than disciplined concision for an 8-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?

No output schema and no annotations mean the description bears full explanatory load for an 8-parameter mutation tool. It omits category semantics, confidence meaning, evidence format, project scoping, and auth requirements, leaving the agent without enough to call it precisely.

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 8 parameters, so the description must compensate and largely does not. The example ('Use pnpm, not npm') loosely illustrates the required 'statement' field, but agent, api_key, project, category, evidence, task_type, and confidence are entirely unexplained.

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

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

The description states a specific verb and resource ('Record a user preference/taste/convention') and even gives a concrete example, so the purpose is immediately clear. However, it does nothing to distinguish itself from closely related siblings like 'remember' and 'record_decision', which also persist knowledge.

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 and no indication of how this differs from 'remember' or 'record_decision'. 'Repeats reinforce confidence' is a behavioral note, not an instruction about when this tool should be selected over its siblings.

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

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

No annotations are provided, so the description carries the full burden. It never states that this is a read-only aggregation, whether api_key authentication is required, whether calling it mutates state (e.g. claims or consumes inbox items), or how the ranked output is shaped.

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 that front-loads the session-check-in framing before listing contents. Every clause adds a returned artifact; no filler, though the noun pile-up is slightly hard to parse.

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 annotations, no output schema, and four undocumented parameters, the description does useful work by naming the returned payload categories, which partially substitutes for a missing output schema. It still leaves authentication, mutation behavior, and parameter meaning 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?

Four parameters with 0% schema description coverage and no mention in the description. 'agent', 'api_key', 'project', and 'max_tokens' are entirely undocumented, and the description does not compensate by explaining scoping or token-budget behavior.

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

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

States a specific verb-scope (start-of-session check-in) and enumerates what it aggregates: ready subtasks, inbox, leftovers ranked by expertise, and user preferences. That enumeration distinguishes it from single-purpose siblings like board, msg_recv, and who, though the name 'pickup' alone carries no meaning.

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?

'Start-of-session check-in' implies the moment to use it, but there is no explicit when-not guidance and no named alternative for narrower needs (e.g. use board or msg_recv if you only want one slice). Usage is implied 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?

No annotations are provided, so the description carries the full behavioral burden. "Log" implies a write, but nothing is said about persistence, duplicate handling, required auth (an api_key parameter exists but is unexplained), or what happens to the aliases. Only a hint of downstream behavior (later retrieval via why()) is 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?

A single dense sentence with the core action front-loaded and no filler. It is compact, though the alias-heavy phrasing slightly increases parsing effort for an agent.

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 write tool with no annotations and no output schema, the description is too thin: it omits meaning for most parameters, says nothing about auth/credentials, required inputs, or return values. An agent can call it but not confidently populate 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 0% with 13 parameters, so the description must compensate. It names only 5 concepts (what/decision, why/rationale, related_ids) and helpfully documents the alias pairs, but 8 parameters (tags, agent, api_key, project, entities, evidence, session_id, alternatives) are completely 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+resource ("Log a decision") and the key payload fields (rationale, related_ids). It also ties the tool to the sibling `why` by explaining the downstream use ("so other AIs can later ask why()"), giving partial sibling differentiation, though it does not contrast with `remember`, `observe_preference`, or `add_leftover`.

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

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

Usage is implied rather than stated: the reader infers they should call this when they want a decision retrievable later via why(), and the linking instruction ("Link code/memory ids via related_ids") gives a concrete action. There is no explicit when-to-use vs when-not, and no mention of the other recording siblings 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?

With no annotations, the description carries the full burden. It usefully discloses non-obvious behavior: secrets are auto-redacted, env:// refs are the recommended pattern, visible_to restricts readership, and subject/predicate/value enable conflict detection. It does not disclose mutation semantics, whether duplicates are merged, or anything about the response.

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, followed by tightly packed parameter notes. Semicolons compress several distinct facts efficiently. It is dense but not padded, and nothing reads as 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 16-parameter write tool with no annotations and no output schema, the description covers the highest-value concepts (aliases, fact triple, entity linking, visibility, redaction) but omits half the parameters and all return/side-effect information. 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% across 16 parameters, so the description must compensate entirely. It documents content (with text/fact aliases), subject/predicate/value, entities, and visible_to, but leaves kind, tags, agent, title, api_key, project, session_id, and related_ids completely unexplained 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+resource ('Store a memory') and enumerates the kinds of things stored (note, observation, fact). It does not differentiate from close siblings such as record_decision or observe_preference, which also persist structured information, so an agent gets a clear purpose but no routing signal.

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 and no mention of alternatives. The line about supplying subject/predicate/value 'for facts' is parameter guidance for a mode, not tool-selection guidance. An agent cannot tell from this text when to call remember versus record_decision, observe_preference, or add_leftover.

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

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

With no annotations, the description carries the full behavioral burden and only discloses one trait: cost is estimated from a price table when omitted. It says nothing about authentication (an api_key parameter exists), idempotency, whether repeated reports double-count, or what happens to unspecified fields, which is a significant gap for an 11-parameter mutation tool.

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

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

A single dense sentence with no filler, and the key fallback behavior (cost estimation) is placed in a parenthetical immediately after the main action. 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 tool with 11 optional parameters, no annotations, and no output schema, the description is markedly under-specified. It omits required-vs-optional expectations, whether api_key is mandatory, and the relationship between job_id/subtask_id and other tracking tools, so an agent cannot confidently invoke it.

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

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

Schema description coverage is 0% across 11 parameters, so the description must compensate and largely does not. It maps 'tokens' and 'time' loosely to tokens_in/tokens_out and seconds and explains the cost fallback, but agent, model, job_id, subtask_id, project, note, and api_key are left entirely unexplained.

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

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

States a clear verb ('Log') and the resource being logged (tokens/cost/time you spent), so an agent immediately knows this records usage data. It does not differentiate from any sibling, but the siblings listed (msg_send, board, heartbeat, etc.) are obviously unrelated, so the gap is minor.

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 alternatives, whether it should be called per-task or per-turn, or any prerequisites. The mention of the price table is a behavior detail, not usage guidance. The agent must infer timing and cadence entirely.

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

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

No annotations are provided, so the description carries the full burden. It lists returned content (a partial substitute for a missing output schema), but says nothing about authentication (an api_key parameter exists), side effects, idempotency, or what 'latest one in a project' fallback behavior implies.

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 padding; the parenthetical scoping is compact. It is efficient, though terseness here contributes to under-specification rather than clarity.

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

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

For a tool with 5 undocumented parameters, no annotations, and no output schema, the description is thin. Its enumeration of return content helps slightly, but critical invocation details (auth, token budget, session vs project selection) are 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 0% for 5 parameters. The description only obliquely references 'project' and 'session' and never explains agent, api_key, or max_tokens (with its default of 1200). It does not compensate for the total lack of schema documentation.

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 'pick up' and resource 'session' are identifiable, and the description hints at the payload (handoff packet, state, session items, recent context). However, it does not distinguish itself from the sibling tool 'pickup' or from 'handoff', leaving the agent unable to tell which session-retrieval tool to choose. Purpose is implied rather than stated cleanly.

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 guidance, no prerequisites, and no mention of when NOT to use it. With siblings named 'pickup', 'handoff', and 'board', the absence of any routing rule is a real gap.

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

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

With no annotations, the description carries the full behavioral burden and does reasonably well: it discloses the return shape (one-line hits with ids), the effect of context=N (adds N neighbouring turns), and the accepted time formats (ISO or 7d/12h) plus as_of and explain semantics. It omits default limits, permissions/scope, and pagination, which keeps it short of a 5.

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

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

Very dense and front-loaded: the core capability leads, then output shape, then filters, in a compact semicolon-separated form with no filler sentences. The packing is slightly terse, which costs a little readability, but 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 16-parameter tool with no annotations and no output schema, the description covers the essentials: output shape is stated so no return-value schema is needed, and most filter parameters are explained. Remaining gaps (mode, limit, rerank, max_tokens, format) are minor and largely self-evident, so it is close to complete.

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

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

Schema description coverage is 0%, so the description must compensate, and it explains roughly half the parameters with real meaning: context, project, agent_filter, tags, kinds, entity, since/until with format syntax, as_of, and explain. It leaves mode, limit, query, format, rerank and max_tokens uncovered, but the semantic additions it does provide are substantial.

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 clearly: hybrid search combining keyword, meaning, entities, time and recency, with a defined output (one-line hits with ids). It also distinguishes itself from the expand sibling by delegating detail retrieval to it. Only the generic name 'search' and the unstated corpus (implied to be turns/memory by 'neighbouring turns') keep it from a 5.

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

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

The description implies a workflow ('Returns one-line hits with ids; expand(id) for detail'), which routes the agent to the expand sibling for full detail. However, it never explicitly states when to choose this tool over others or what conditions argue against it, so usage is implied rather than prescribed.

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

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

No annotations are provided, so the description carries the full burden. It discloses useful behavior (returns instructions and files 'to follow now', nothing to install, sourced from Commons), but says nothing about authentication despite an api_key parameter, nor about rate limits or mutability of the fetched content.

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 paragraph that front-loads the primary use case before branching to the query and fallback modes. The parenthetical framing is dense but each clause carries routing or behavioral information, with little waste.

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 5-parameter tool with no annotations, no schema descriptions, and no output schema, the description does explain the return shape (instructions + files) well, but leaves the auth parameter and the 'agent' parameter unaddressed. Adequate for the main path but incomplete for anything requiring credentials.

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 5 parameters, so the description must compensate and only partially does: it covers 'name', 'query', and implies 'include_files' via '(and its files)'. The 'agent' and 'api_key' parameters are entirely unexplained in both schema and description, leaving auth requirements undocumented.

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

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

States a specific verb+resource: it fetches a skill's full instructions and files, with an explicit mention that the query form finds skills. It differentiates itself from skill_help by category. However, the presence of an undocumented 'agent' parameter leaves a possible third mode of operation unclear, slightly muddying the purpose.

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 between the two call signatures (skill(name) to run, skill(query=...) to find) and names the fallback skill_help with the condition that selects it ('Can't run it... a tool, access or environment you lack'). It lacks any exclusion guidance relative to the broader retrieval siblings like search or expand.

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

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

No annotations are provided, so the description carries the full burden, and it delivers real behavioral context: the task is delegated to an agent holding the skill, live agents are preferred, and the result is returned asynchronously via msg_recv. It omits failure behavior (what happens if no qualifying agent exists) and timing, keeping it short of a 5.

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

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

A single front-loaded sentence with the purpose up front, followed by the routing detail in a colon clause. Dense and efficient, though the nested parenthetical and clause add slight load.

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

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

Behavior and return channel are covered, which is valuable given no annotations and no output schema. However, with five undocumented parameters and no failure/fallback information, the definition is not complete enough for an agent to invoke it confidently.

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

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

Five parameters with 0% schema description coverage, yet the description never maps or explains any of them (name, task, why, agent, api_key). An agent cannot tell from the text what 'name' identifies or what 'why'/'agent' are for, 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+resource: 'ask for help with a skill you can't run', and explains the routing mechanism (Commons hands the task to an agent that has used or holds it). It clarifies intent well but does not explicitly distinguish itself from adjacent siblings like skill, summon, or handoff.

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

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

Gives a clear triggering condition with three concrete cases (missing tool, access/environment, a skill only another agent has), so an agent knows when this applies. It stops short of naming alternatives (e.g., 'use skill directly if you can run it') or 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the status semantics, the ownership window ('yours until finish_work or handoff'), force/reason semantics, and that `related` lists connected memories - but it never mentions auth (api_key), what persistence/claiming actually happens, or race/conflict behavior, leaving meaningful behavioral gaps for a state-changing tool.

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

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

Dense and front-loaded ('Before ANY task...'), with a branch structure that earns its space. Slightly cluttered notation (backtick references, terse branch fragments) and the bare `related` reference add minor ambiguity, but little 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?

With no annotations, no output schema, and 0% param coverage across 7 params, the description must carry everything. It adequately covers the coordination flow and statuses but omits the return shape, auth/project/agent parameter meaning, and any conflict/race handling, so an agent still has unresolved questions before calling it.

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

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

Schema coverage is 0% across 7 parameters, so the description must compensate. It explains the semantics of force, reason, and paths, but leaves what, agent, api_key, and project entirely undocumented, covering only about half the parameters that actually need explanation.

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 clear action (check a task against other agents' live/finished work before starting) and routes ownership via status branches, and it names siblings finish_work and handoff implicitly to define scope. It is distinguishable from those siblings, though the core 'claim/start' action is conveyed indirectly through the 'ok = yours until finish_work' phrasing rather than stated outright.

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

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

Explicitly says 'Before ANY task' and gives when-to-use/when-not branching: busy = don't start, done = build on it only with force=true + reason for a real follow-up. It names the alternative and the exact condition that selects each path, leaving little 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?

With no annotations, the description carries the full burden, and it does disclose real behavior: the auto plan chain resolves to a model, then a live agent, then rules, and the sdlc pattern requires the user to approve the spec and confirm before shipping. It stops short of saying whether submission blocks, what is returned, how dedupe behaves, or what budget exhaustion does, which are material for a fan-out/mutation tool.

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

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

It is information-dense and the core action leads, but the body degenerates into a semicolon-and-pipe run-on that mixes pattern names, the sdlc workflow, dag field lists, and budget keys in one block. No wasted words, but the structure makes it harder to parse than a short bulleted breakdown would.

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 an 11-parameter tool with nested objects and no output schema, the description covers the structurally complex arguments well but omits return behavior, blocking semantics, and several scalar parameters. An agent could invoke it, but not confidently predict the outcome.

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

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

Schema description coverage is 0%, so the description must compensate for 11 parameters. It does solid work on the complex ones (pattern values, stages, the dag entry shape, budget sub-keys, context_pack as a prefix, agent as a step pin), but leaves n, dedupe, api_key, and project entirely unexplained, so coverage is partial rather than complete.

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

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

The opening sentence gives a specific verb and resource ('Split a task across the agents'), which cleanly separates it from siblings like claim_subtask, start_work, and handoff that consume rather than create work. It never names those siblings, so differentiation is achieved by implication rather than explicit routing.

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 enumerates the pattern choices (auto, plan_execute_verify, cross_review, debate, consensus, parallel, sdlc, dag) and describes what 'auto' falls back through, which is genuine in-tool selection guidance. It never says when to reach for submit_task versus the surrounding lifecycle tools (claim_subtask, start_work, pickup), so usage is implied rather than stated.

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

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

With no annotations, the description carries the full load and does well: it discloses latency behavior (daemon/live-stream agents start within a second, others woken via channels) and that the result tells how to make unreachable agents wakeable. It omits auth expectations (api_key) and any rate/side-effect caveats.

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 and default scope, followed by dense but relevant behavioral detail. Three sentences with little waste, though the behavioral sentence is somewhat packed.

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 6-parameter tool with no annotations and no output schema, the description should carry more: it never explains wait, api_key, or project, and gives no return-shape detail beyond a single hint. The core behavior is covered but the parameter surface is largely 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 0% across 6 parameters, yet the description only explains `reason`. `wait`, `api_key`, and `project` are entirely undocumented, and agent/agents selection is only implied by the default scope. The description does not 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 action (call/wake other agents) and an outcome (see who is ready), with a default scope (every agent except you). It is distinguishable from messaging siblings like msg_send, though 'see who is ready' overlaps conceptually with the `who` 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?

The description implies when the tool is useful (waking agents to work now) and explains which agent states respond quickly, but it never explicitly names an alternative (e.g. msg_send, who, turn) or states when NOT to use it. Usage is left to inference.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: catalog size, that the client under-reports it, the returned fields (name, summary, arguments), and the empty-query edge case. It leaves the limit/pagination behavior unstated, which is a gap but not a contradiction.

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 what the tool searches, then what it returns, then how to act on the result. Every clause carries information; nothing is redundant.

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

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

No output schema and no annotations, so the description must cover returns and behavior itself — it does state the return fields and the empty-query case. The only real omission is how 'limit' interacts with result size, which leaves the pagination story slightly 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 coverage is 0%, so the description must compensate. It does explain 'query' semantics ('Empty query lists every tool name'), which is genuinely useful, but 'limit' (default 25) is undocumented in both schema and description. Partial compensation for a two-parameter tool.

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

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

States a concrete verb+resource: search the Commons tool catalog, and adds scope ('about 150 tools; your client lists only a few') plus what it returns. The name 'tools' alone would be ambiguous, but the description resolves it. It does not explicitly distinguish itself from the sibling 'search', 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?

Gives a clear trigger ('your client lists only a few') and routes the agent onward: 'run any of them with call(tool, args)', naming the sibling that executes tools. It stops short of 5 because it never states when not to use it, e.g. when the tool is already visible client-side.

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

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

With no annotations, the description carries the full burden. It usefully discloses a persistent side effect ('stores both word for word') and a read component ('returns what Commons already knows'), but says nothing about auth (despite an api_key parameter), rate limits, ordering, or idempotency of the required every-turn call.

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?

Roughly two sentences, front-loaded with the core instruction and invocation example. Efficient, though the parenthetical syntax example is slightly crowded.

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 6-parameter tool with zero schema coverage, no annotations, and no output schema demands far more than this description provides. Auth, the four undocumented parameters, and behavior of the returned knowledge are all absent.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate. It only documents two of them (user_message, reply) and even those without real semantics, leaving agent, api_key, project, and conversation entirely unexplained.

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

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

The description states a specific dual function (store the exchange word-for-word and return what Commons already knows about the message), which is meaningful. However, 'turn' is an opaque name and the framing ('Chat apps without hooks') is confusing rather than clarifying. It does not differentiate from the many sibling messaging tools (msg_send, msg_recv, msg_get), leaving the agent to guess the relationship.

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 explicit timing guidance: 'call on EVERY turn, before answering,' which is exactly the when-to-use context an agent needs. It stops short of naming alternatives or stating when NOT to call it (e.g., once a hook exists), so it falls just shy 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?

With no annotations, the description carries the full burden and does well: it discloses that the raw key is never exposed, that a decision agent gates the call by risk class, that chat 'yes' cannot approve, and that a running verdict means the call is already in flight. It omits error handling, rate limits, and return-shape details.

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

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

Purpose is front-loaded and every clause carries operational content (approval flow, verdict handling). The dense run-on semicolon style is harder to parse than it needs to be, but there is little wasted text.

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

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

For a complex tool with an approval workflow, 8 params, no annotations, and no output schema, the workflow side is well covered but the parameter side is not. An agent still cannot tell what api_key, body, content_type, or agent should contain.

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

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

Schema coverage is 0% across 8 parameters, yet the description only explains 'justification' (what you need it for) and alludes to 'credential' via 'one of the user's keys'. It leaves body, agent, method, content_type, and especially the api_key-vs-credential distinction completely undocumented.

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

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

States a specific verb and resource ('Call a service with one of the user's keys') plus the key constraint ('without seeing it: Commons makes the request and returns the response'). Clear enough to distinguish from credential-management siblings, but it never names the sibling 'call', which an agent may confuse with this 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?

Provides real routing rules: sound reads are allowed, writes need the user's request, risky ones wait for the user, and it prescribes the approve_url / approval_status(question_id, wait=120) flow. It also tells the agent not to resend when verdict is 'running'. It stops short of naming an alternative tool to use instead.

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

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

With no annotations, the description carries the full burden and does so richly: encryption at rest, that other agents use the key without seeing it, the auth encoding formats, the risk enum's behavioral consequence ('high: every write asks the user'), and the deferred-send semantics of base_urls. This is exactly the behavioral context annotations would otherwise supply.

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 leads the paragraph, then parameter guidance follows in a logical order. It is dense and parenthetical-heavy, but for a 13-parameter tool most sentences earn their place; a few could be broken into clearer structure.

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

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

For a 13-param mutation tool with no annotations and no output schema, the description covers purpose, usage, permissions, and most parameters. Remaining gaps are minor parameter definitions (agent, api_key, extra_headers) and any indication of what a successful deposit returns, but the agent has enough 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 coverage is 0% across 13 params, so the description must compensate, and it explains the non-obvious ones well: purpose, scope (with provider-level examples), used_in (with a concrete object shape), base_urls, auth (with the full bearer|basic|header|query grammar), and risk. It omits meaning for agent, api_key, extra_headers and description, which is the only reason this isn't a 5.

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

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

States a specific verb+resource ('Hand over an API key, token or password ... so Commons keeps it (encrypted)') and immediately distinguishes the resource from its sibling by naming use_credential as the consumption path. An agent knows this is the deposit side of a credential store 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?

Explicitly instructs when to act ('Deposit it the moment you get it') and routes to alternatives for deferred work ('or add them later with vault_note', 'until vault_hosts sets them the key is never sent anywhere'). It also states the permission boundary ('You can add new keys and update your own, not replace another's'), so the agent knows when this tool will and won't work.

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

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

With no annotations the description carries the full burden, and it delivers meaningfully: it discloses that the card is authored by the hub from verifiable facts (key issuance, runtime, wake path, usage headroom, schedules, completed work) while the agent's own statements are kept separate as 'claimed'. This provenance/trust distinction is high-value behavioral context. It omits auth requirements (an api_key param is present) and any read-only confirmation.

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 mode split, then the card's provenance, then the usage trigger. The parenthetical inventory is long but each item earns its place. Dense but 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?

There is no output schema, and the description usefully sketches both return shapes (one line per teammate; the card's contents). However, with three parameters at 0% schema coverage it leaves api_key and the name/agent distinction unexplained, so the definition is only minimally complete for calling 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 coverage is 0%, so the description must explain three parameters. It clarifies the optional-name behavior (list vs card), but never explains the api_key parameter or how the 'name' and 'agent' parameters differ, leaving two of three parameters semantically ambiguous and one entirely undocumented.

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

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

States a specific resource and two distinct modes: with no name it lists teammates one per line, with a name it returns that agent's card. An agent can tell it apart from a self-lookup like whoami. It stops short of naming that sibling explicitly, so it is clear but not fully differentiated.

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?

Closes with an explicit when-to-use: 'Use it before handing work to an agent or acting on a request from one.' That is a concrete trigger. No when-not guidance or named alternatives are given, which keeps it from 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses cost ("cheap"), safety ("safe to call any time"), and the exact return content including the `commons-ok` sentinel. It does not state whether the call requires a valid key or what happens on an unauthenticated call.

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

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

Two short sentences, front-loaded with the operation type, no filler. Every clause conveys information (purpose, return values, cost, safety).

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

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

For a trivial, side-effect-free tool with no output schema, the description substitutes well by naming the returned fields and flagging cost/safety. The remaining gap is the two undocumented input parameters, which neither the schema nor the prose explains.

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 two parameters (`agent`, `api_key`), and the description only obliquely implies a key exists via "which agent this key belongs to." It never explains what `agent` is for or whether either parameter is meant to be supplied by the caller.

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 function (connection/identity check) and enumerates the return payload: which agent the key belongs to, the server version, and the `commons-ok` marker. It never differentiates from the near-identical sibling `who`, so an agent must infer the distinction.

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?

"Cheap; safe to call any time" gives a general usage signal and the "Connection check" framing implies the use case, but there is no explicit when-to-use condition and no mention of alternatives such as `who` or `credentials`, which likely overlap.

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

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

No annotations are provided, so the description carries the full burden. It says nothing about what the explanation looks like, whether it is derived from stored records, whether it requires prior context, or what the cost/latency profile is; only the acceptable query forms are disclosed, which is a small behavioral hint.

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 key input clarification front-loaded and no filler. It is not padded, though the terseness is part of why other dimensions are under-specified.

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 annotations, no output schema, three parameters and zero schema descriptions, the description is too thin for the tool's apparent complexity. An agent still cannot tell what an 'explanation' contains, how ids are resolved, or what 'project' and 'max_tokens' do.

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

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

Schema description coverage is 0%, so the description must compensate, and it only covers one of three parameters: 'query' is clarified as free text or an id of a symbol, memory, or session. The 'project' and 'max_tokens' parameters receive no explanation at all, leaving a substantial 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 is 'explain' and the object is 'the logic behind something', which is broad enough to be ambiguous on its own. The clause naming the accepted query forms (free text or symbol/memory/session id) gives a clearer picture of scope, but the phrase 'something' keeps the purpose fuzzy rather than crisply differentiated from siblings like 'who' or 'search'.

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

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

There is no guidance on when to call this versus 'search', 'expand', 'remember', or 'who'. The description lists what the query can contain but never states the condition or situation that should select this tool over the many explanation-adjacent siblings.

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