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

With no annotations, the description carries the full burden of transparency. It describes what the output contains (agent work, owner buttons, blocked items, overdue/due-soon) and even details the owner-kind/role condition. However, it does not explicitly state whether the tool has side effects or is read-only, and it omits mention of truncation behavior (which is only in the parameter schema). Still, the description goes a long way in explaining the tool's behavior.

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

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

The description is two sentences: the first defines the scope, the second differentiates from siblings. It is information-dense but not overly long. The structure is logical and front-loaded with the core concept, making it easy to parse. Minor deduction for the slightly run-on first sentence, but overall it is concise.

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

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

The tool has no output schema and no annotations, so the description must provide a complete picture. It does well explaining the purpose and usage alternatives, and partially describes the output categories. However, it leaves the 'project' parameter unexplained and doesn't mention the trimming/truncation behavior (which is only in the parameter schema). Without that, the agent may not know how to use the tool fully or interpret results, so completeness is only moderate.

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

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

Schema description coverage is only 50%: the 'full' parameter has a description, but 'project' has none. The main description does not mention 'project' at all, so the agent has no idea what filtering by project does. The description fails to compensate for the undocumented parameter, leaving a clear semantic gap.

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

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

The description clearly states what the tool does: it splits the day by who can act (agent work, owner's buttons, blocked items, overdue/due-soon). It also distinguishes itself from hub_brief and hub_inbox by explicitly stating the different question it answers, making the purpose very specific and well-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?

Usage guidance is explicit: it names alternative tools (hub_brief, hub_inbox) and explains when this tool is appropriate vs. when it is not. The description also lists the specific categories of work it focuses on, giving the agent clear decision criteria for selection.

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

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

With no annotations provided, the description carries the full burden and does so admirably. It discloses the safety profile (read-only by default), the side effects of `apply` (files incident tasks and writes one report), idempotency (findings are keyed so weekly runs never duplicate), and the distinction between reported numbers and filed violations.

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

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

The description is long but every sentence earns its place: it enumerates the specific checks, explains the rule-provenance rationale, clarifies read-only vs. apply behavior, and warns against misusing it as a dashboard. The structure front-loads the core purpose followed by details, making it easy 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?

Given the complexity of the tool (5 parameters, no output schema, no annotations), the description is remarkably complete. It covers what the tool does, the exact checks it performs, how to trigger writes, idempotency guarantees, output caveats (numbers are not violations), and the parameter semantics for the access-control field `by`. No significant gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining the relationship between `by` and `apply` ('required with apply') and clarifying that `full` affects context trimming. This goes beyond the raw parameter descriptions but does not deeply elaborate every parameter, which is acceptable given the schema's completeness.

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 precise verb and resource: 'Compare what the hub DECLARES with what actually happened, and turn each disagreement into an incident somebody owns.' This clearly distinguishes the tool from sibling tools by framing it as an audit/incident-creation process, not just a reporting or syncing 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?

The description gives explicit guidance on when to use the default read-only behavior vs. the `apply` mode ('Read-only by default; `apply` files one incident task per finding'). It also states what the tool is not ('NOT a dashboard'), which helps set expectations. However, it does not explicitly name alternatives or contrast with sibling tools like `hub_report` or `hub_lint`.

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 provided, the description carries the full behavioral burden and does so thoroughly. It explicitly states 'It reports only', clarifies that nothing is filed without an explicit hub_audit apply, explains that review embeds hub_lint and hub_audit findings, and disambiguates subtle behaviors like staleDigests and per-reader cursors for broadcast roles. This fully compensates for the missing annotations.

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

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

The description is front-loaded with the core purpose and a list of report contents, then adds necessary disambiguation of buttonItems versus ownerWaiting and the audit boundary. It is dense and somewhat run-on, but every sentence provides useful behavioral or conceptual detail rather than filler.

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

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

For a read-only brief tool with no output schema and no annotations, the description is remarkably complete: it enumerates every major section of the result, explains truncation behavior, references configuration for owner queues, and clearly states the side-effect policy. An agent has enough context to invoke the tool and interpret the returned report without hidden surprises.

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?

All four parameters are already described in the input schema with clear meanings (full, hours, staleDays, reviewLimit), so the baseline is 3. The description reinforces concepts like reviewLimit being about finding kinds and full controlling truncation, but it does not add significant meaning beyond what the schema already provides.

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

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

The description clearly identifies a concrete resource and behavior: a morning brief aggregating open tasks, journal entries, stale cards, claims, queue depth, buttons, and review findings across all projects. It is specific enough to be understood without opening the schema, though it does not explicitly name or contrast sibling report tools such as hub_report, hub_status, or hub_agenda.

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

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

The description gives strong when/when-not guidance: it is a read-only morning rollup, and any intended filing or mutation requires an explicit hub_audit({apply:true}) carrying somebody's name. It also explains that the audit/review rides along on this call instead of waiting to be remembered, and distinguishes ownerWaiting from 'what can I start' lists, which helps the agent route correctly.

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 existing hand-written frontmatter and Facts are preserved, that 'digest' replaces the entire text, and — crucially — that a 'from' not present in the digest is an error rather than a silent no-op. It does not cover permissions/auth or create-vs-update conflict behavior, so it is not fully exhaustive.

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

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

Four tight sentences, front-loaded with the core action, then usage, then preservation guarantees, then patch mechanics. No filler; each sentence contributes distinct information (what, when, side effects, patch semantics).

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 mutation tool with no annotations and no output schema, the description covers purpose, alternatives, preservation, patch modes, and error semantics well. It omits return/confirmation format and any permission requirements, which leaves a minor gap but not one that would cause a mis-call.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds real semantics beyond the schema: 'digest' fully replaces the text and should be omitted when patching, and unmet 'from' targets raise an error (the schema only says each must occur exactly once). These clarifications justify going above baseline.

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?

Starts with a specific verb+resource ('Create or update a project card') and immediately scopes it ('from just a name and a digest — no folder needed'), explicitly contrasting with the sibling hub_sync. It also distinguishes the two operating modes (replace vs patch), so an agent can identify the tool and its scope without opening the schema.

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

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

Gives explicit when-to-use ('capture a project that is not a local git checkout, e.g. when harvesting a dialog') and an explicit alternative ('unlike hub_sync'). It further routes intra-tool behavior: use patch ('replace'/'appendLine') rather than a full replace to fix one stale line without disturbing the owner's framing.

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

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

No annotations exist, so the description carries the full burden. It discloses the most important behavioral trait — the lock is not enforced — plus the matchable:false consequence for prose areas. It omits TTL semantics (does it auto-expire at ttlMin?) and what happens on conflicting/duplicate 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 behavior ('Soft-lock a work area'), then the critical not-enforced caveat, then the area format. Dense but every clause adds value; the parenthetical example list is slightly heavy but justified for a glob field.

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-param mutation-like coordination tool with no annotations and no output schema, the description covers purpose, effect, key-param format, and cross-tool consumption well. Remaining gaps — TTL behavior, conflict handling, and the non-documented params — are the main shortfall.

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

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

Schema coverage is only 40%, so the description must compensate. It richly explains `area` (glob syntax, examples, joined with ' + ', bare directory allowed, prose accepted), which is the critical parameter. `agent`, `note`, and the default-240 `ttlMin` are not elaborated in the description, leaving minor gaps.

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+resource: 'Soft-lock a work area' with the purpose of visibility to other agents. It explicitly distinguishes the tool's effect from a hard lock ('Not enforced — informational') and names the related siblings (hub_claim_check / hub_context) that consume the claim.

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?

Clear context: it tells the agent the claim is informational and that hub_claim_check/hub_context will surface it. It implicitly frames when to use it (coordinating file ownership), but offers no explicit when-not or precedence rules among the ~38 sibling tools.

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

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

With no annotations, the description carries the full burden and does so well: it declares "Pure read" (safety profile), discloses the soft-lock semantics ("this informs, it does not forbid"), and tells the agent the resulting obligation is to coordinate with the holder. It also enumerates the response fields and what `mine` and `unmatchable` mean, which is behavioral context beyond any structured field.

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 operative instruction ("Before editing a file") is front-loaded, and the return-field enumeration earns its place because no output schema exists. It is dense but largely waste-free; the parenthetical clarifications add precision rather than 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?

There is no output schema, so the description must describe returns — and it does, naming free, holders, mine, and unmatchable. Combined with the read-only and soft-lock disclosure, an agent has everything needed to call this correctly before an edit.

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

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

Schema coverage is 100%, so the baseline is 3. The description rises above it by explaining the effect of `agent` (own claims reported as `mine`, not as holders) and the semantics of `unmatchable` relative to the project, tying parameters to output meaning rather than merely restating 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 (check whether a file is inside a live claim), scoped to a file path, and frames it as a pre-edit interrogation. It is clearly distinguishable from the sibling hub_claim (which creates claims), and it even previews the return shape, so an agent needs no schema peek to know what this does.

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

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

"Before editing a file" gives an explicit trigger condition that tells the agent exactly when to invoke it. It stops short of naming the alternative or an explicit when-not, but the timing and coordinate-with-holder guidance make the intent unambiguous.

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

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

With no annotations the description carries the full burden and delivers: it discloses the three-tier resolution order (marker file, project card path, folder-name guess with guessed:true), the failure mode (project null + hint), and a subtle caveat that digestStale can read current while being months behind. This is deep behavioral context beyond anything structured.

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

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

Front-loads the core purpose and every clause earns its place by describing resolution order, return fields, and caveats. It is dense and slightly run-on with heavy em-dash usage, but not padded.

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

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

No output schema exists, so the description must explain the return — and it enumerates every field (project, via, root, guessed, digest, openTasks, presenceHere, journalTail) with meaning. For a read-only session-bootstrap call, nothing an agent needs is missing.

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

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

Schema description coverage is already 100%, so the schema documents all five parameters (including why cwd cannot be inferred). The description reinforces a few meanings (journalTail content, staleDays rule) but adds little the schema does not already carry — the 3 baseline is appropriate.

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

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

States a specific verb and resource ('Resolves which hub project YOUR working directory belongs to') and frames the scope as 'Where am I' for session start. It is clearly distinct from siblings like hub_get/hub_status, even naming hub_status as the source of the same stale verdict.

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 tells the agent when to call it: 'the first call of a session and the first call after a context compaction.' That is a strong usage trigger, though it stops short of naming an alternative tool to use instead in other situations.

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 transparency burden. It discloses a key behavioral trait: long lists are trimmed by default, with omitted data reported in `truncated`, and the `full` flag disables this. This goes beyond the schema and helps the agent understand output limits.

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

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

Two sentences, each earning its place. The first defines the returned data, the second gives contextual usage instruction. No fluff or repetition.

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

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

For a simple read tool with 2 parameters and no output schema, the description covers the core payload (card, journal entries, soft-locks) and the trimming behavior. It doesn't explain return formatting, but that is not essential for a get-tool of this complexity.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents them. The description adds no additional parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it returns 'Everything about ONE project' including its full card, recent journal entries, and active soft-locks. The verb is implicit in the name but the resource and scope are specific, distinguishing it from siblings like hub_status (project list) and hub_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?

Explicit usage guidance is provided: 'Use after hub_status or hub_search points you at a project.' This tells the agent exactly when to invoke this tool and implies it is not for initial discovery.

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 burden. It discloses the return payload ('nodes, edges, and dangling links') and the edge keying mechanism. It does not mention truncation behavior (which is in the schema only), permissions, or other side effects, but for a read-only query tool this is adequate.

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

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

The description is two concise sentences, front-loaded with the core purpose and immediately followed by key behavioral details. Every sentence earns its place with no redundancy.

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 graph query tool with three parameters and no output schema, the description provides sufficient context: it specifies the return types (nodes, edges, dangling links) and the available filters. It could go deeper into edge semantics, but the schema covers parameter details and the overall purpose is clear.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'filter by project or type' which aligns with the schema, but adds no extra semantic detail beyond what the schema already provides.

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

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

The description clearly states the tool's function: it provides a typed relationship graph across projects and resources, showing dependencies and deployments. It distinguishes itself from sibling tools by focusing on relationships rather than individual records, and explains the edge structure via frontmatter links.

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

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

The description implies when to use it (when you need relationship data) and mentions filters by project or type. It does not explicitly name alternatives or exclusions, but the focused description makes its use case clear.

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?

Without any annotations, the description carries the full burden and does so excellently. It discloses the destructive overwrite behavior, the freshness semantics (judged at read time from ttlMin, default 15min, same pattern as hub_claim), the 5-minute throttle on the node snapshot refresh, and the node-local directory that never syncs. This is exactly the kind of hidden behavior that an agent needs to make correct consequences.

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 sentences each carry active operational content: purpose and when, overwrite/timeout semantics, and a rarely surfaced cross-node refresh constraint. The core instruction is first in the lineup, and each sentence earns its place without filler or repetition.

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 six optional parameters and no output schema, the description provides all the practical facts required for a safe call: when to invoke it, what record is overwritten, how freshness is judged, and why a cross-node snapshot is needed. It also accounts for the asymmetric cross-node visibility issue, which is the most non-obvious piece of 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?

The schema covers 100% of the parameters with detailed descriptions, so the description does not need to repeat them. It adds only minimal extra parameter-level meaning—ttlMin's freshness role and role's link to hub_brief—and even that mostly reiterates what is already in the schema. The description primarily enriches behavioral context rather than parameter definitions.

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 first phrase, 'Record that an agent is alive,' uses a specific verb and resource, then sharpens the intent by placing it in an explicit call sequence: 'call it each work cycle (right after hub_report, before the next hub_queue_wait) so... show up in hub_presence.' This clearly separates the heartbeat tool from its more than 30 siblings, including hub_report, hub_presence, and hub_claim.

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 context and a precise time to call the method: 'each work cycle (right after hub_report, before the next hub_queue_wait)' and explains the rationale for MCP/headless agents. It does not mention an explicit when-not-to-use case or list a competing alternative tool, so it falls short of a fully elaborated exclusion clause.

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 provided, the description carries the full burden of behavioral transparency. It discloses what results are returned (blocked reports, overdue tasks, unassigned tasks, expired claim locks), the 'empty:true' response case, and the polling nature. It doesn't cover potential side effects or rate limits, but it is a read-style tool and the description is sufficiently transparent for an agent to understand behavior.

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

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

The description is two sentences, front-loaded with the core value proposition ('What needs a DECISION right now'), and each sentence provides distinct, useful information: the content categories and the polling guidance. No filler or redundancy.

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 list/query tool with two optional parameters and no output schema, the description is nearly complete. It covers the purpose, the specific items returned, the empty response, and usage context. It stops short of detailing the full response shape, but the combination of the schema parameter descriptions and the main description gives an agent sufficient understanding to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description adds no extra parameter meaning beyond the schema; the schema already documents 'full' and 'hours' with clear descriptions. Therefore, the description neither adds nor detracts from what the schema provides.

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

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

The description explicitly states the tool's purpose: 'What needs a DECISION right now', and enumerates specific categories (blocked reports, overdue tasks, etc.). It also differentiates from hub_brief by noting 'not a time window like hub_brief', making it clear what this tool does that others don't.

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 direct usage guidance: 'poll this instead of re-reading hub_status/hub_brief every cycle' and clarifies the distinction from hub_brief. This explicitly tells the agent when to use this tool over 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?

Without annotations, the description must carry the behavioral burden. It indicates read-only nature via 'read-only web kanban' and lists returned data, but does not disclose side effects, auth needs, or truncation behavior beyond what is already in the schema.

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

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

Two concise sentences, front-loaded with the core 'board as data' concept, and each clause adds meaningful detail without redundancy.

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

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

The description sufficiently explains what the tool returns and its relationship to the web kanban. The only minor gap is lack of explicit mention of read-only safety, but the 'read-only web kanban' wording implies it.

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

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

Schema coverage is 100% and the single parameter 'full' is well-documented in the schema, explaining uncapped returns and truncation reporting. The description adds no extra parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns the kanban board as data, specifying the exact categories (queued/in-progress, done-in-last-day, journal) and flags. It distinguishes itself from sibling tools by tying to the read-only web kanban view.

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 this tool is for retrieving board-oriented task data, but it does not explicitly state when to use it over alternatives like hub_task_list or hub_agenda, nor any 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?

With no annotations, the description carries the burden of behavioral disclosure. It clearly states 'Read-only, never files anything,' and describes the structure of findings (enforcement status and local rule quote). It also hints at default truncation via context. This is solid, but it does not cover all possible edge cases or error scenarios, so it is 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?

The description is compact, consisting of two sentences, with the key purpose stated first. The opening phrase is poetic but communicates the core value proposition. It earns a 4 for being reasonably efficient and front-loaded, though it could be tightened by removing the metaphorical opening.

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

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

Given the lack of annotations and output schema, the description does a good job of outlining what the tool does, what findings look like, and its side-effect-free nature. It misses a few details like return format or how to interpret the 'strict/opt-in' distinction, but it is sufficient for an agent to decide and invoke 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?

The schema already provides full descriptions for both parameters (full and projects), so the schema coverage is 100%. The tool description does not add any parameter-specific meaning beyond what the schema gives; it only mentions read-only behavior, which is orthogonal. Therefore, baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a linter for hub rules, with specific verbs like 'reports' and concrete examples of what it checks (e.g., money bets without dates, human-owned tasks without prep). It also distinguishes itself from siblings by focusing on the gap between enforced and merely documented rules. However, it does not explicitly name or contrast with sibling tools, which keeps it one step below a perfect score.

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 usage: run this to check rule enforcement and get findings. It does not provide explicit when-to-use vs alternatives, nor does it mention any exclusion criteria. The context signals include many sibling tools, but the description does not leverage them to guide tool selection.

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

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

With no annotations, the description carries the burden of disclosure. It reveals valuable behavioral details: the tool selects a single task, excludes tasks with open dependencies, and can signal whether the action is the owner's or an agent's. It does not detail output structure or potential side effects, but for a decision tool, this is substantive context.

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

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

The description is a tight three-sentence paragraph that is front-loaded with the core purpose. Each sentence adds context—why it's not a list, eligibility rules, and output nuance—without wasted words.

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

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

The description covers the tool's core decision logic and behavioral nuances, but lacks crucial technical details: how the optional parameters affect the selection and what the exact output format is. Given no output schema and no annotations, these omissions make it only partially complete for effective invocation.

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

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

Schema description coverage is 0% and the description makes no mention of the 'project' and 'assignee' parameters. While the names are self-explanatory, the description does not clarify their role (e.g., filtering the decision), leaving a clear gap in the tool's usage.

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

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

The description clearly states the tool identifies the single next task ('The ONE task to do now') and explains why it was chosen. It explicitly distinguishes from list-based approaches, helping differentiate from sibling list tools like hub_task_list and hub_agenda.

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 usage context: use this when you need to decide what to do next, not when you want a list. It mentions ineligibility criteria (open dependencies) but does not explicitly name alternative tools or when not to use it, leaving some room for interpretation.

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 does disclose useful behavioral context: the content topics, that short mode is under 600 words and lists full-manual sections, that full mode is about 4000 words, and that it mirrors HUBD.md. It does not explicitly state that the tool is read-only or side-effect-free, but for an orientation manual that is a minor omission.

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

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

The description is front-loaded with what the tool contains, then tells the agent when to call it, then explains the mode differences. Every sentence contributes useful information, and the length is appropriate for the amount of onboarding context being conveyed.

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

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

For a one-parameter informational tool with no output schema, the description is complete enough: it explains what the orientation covers, when to call it, what each mode returns in terms of length and content, and how it relates to HUBD.md. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, but the description adds substantial meaning beyond the enum values: short mode is under 600 words and lists the sections of the full manual; full mode is the whole manual (~4000 words) and matches HUBD.md. This goes well beyond the schema's 'default short' note.

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 precise function: orientation for a first-time agent, covering channel selection, the author rule, session ritual, and compaction recovery. It clearly distinguishes this tool from siblings like hub_graph, hub_claim, or hub_task_add by framing it as the onboarding manual rather than an operational action.

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 this FIRST the first time you connect.' The mode guidance also tells the agent which variant to choose. It stops short of explicitly saying when not to call it or naming alternative onboarding tools, but the first-time-only framing is clear.

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

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

With no annotations, the description must carry the burden of behavioral disclosure. It reveals that if no card exists, the tool returns a scaffold and instructions for creation. It also implies a read-only nature through the 'never edit' guidance. However, it does not describe the exact return format, whether it only reads, or any other side effects, leaving some ambiguity.

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

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

The description is composed of three sentences and is fairly concise. It front-loads the definition of the operator card, then adds context and the return behavior. It could be tightened by leading with the action verb, but it avoids unnecessary verbosity.

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

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

For a tool with no parameters and no output schema, the description gives a good sense of the concept and the fallback behavior. It clarifies that the operator card is a special, stable resource and that a scaffold is returned if missing. It does not detail the structure of the returned scaffold, but the complexity is low, so this is sufficient.

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 zero parameters, so there is nothing to explain. Per the rubric, the baseline for 0 params is 4. The description adds no parameter information, but none is needed.

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

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

The description clearly focuses on the operator card and its contents (facts, preferences, boundaries), and states that it returns a scaffold if no card exists. However, it never uses a direct verb like 'get' or 'read', so the action is implied rather than explicit. It does distinguish from siblings by describing the unique nature of the operator card.

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 provides context about when this tool is relevant: the operator card belongs to no project and changes slower than other data. It also instructs agents to read Boundaries and never edit them, which implies a read-only usage. However, it does not explicitly state when to use this versus a sibling tool like hub_get or hub_context, nor does it mention any 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 exist, so the description carries the full burden, and it does significant work: it discloses snapshot freshness via heartbeat, the observedOn/alsoOn/coverage/blindTo fields, and the 'invisible ≠ dead' semantic that governs interpretation. It doesn't cover refresh cadence precisely or describe auth/rate behavior, but the behavioral interpretation guidance is strong and specific.

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

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

The description is long and discursively structured: the core capability is buried in a marquee paragraph, followed by an extended war story about a worker dead for 92 hours. That anecdote earns its place as motivation but is disproportionately dominant; the front-loaded 'fleet roster' line is good, yet overall the prose is more essay than field.

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

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

For a read-only roster query with 100% schema coverage and no output schema, the description covers the interpretation-critical parts (coverage/blindTo/observedOn) that structured fields alone wouldn't convey. However, it's weak on concrete usage guidance and doesn't explain the return shape despite having no output schema, leaving some gaps an agent would want filled.

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

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

Schema description coverage is already 100%, with each of the six parameters documented (cwd, full, role, project, aliveOnly, memberDays). The description adds contextual color about coverage and truncation but does not add format or interaction detail beyond what the schema already provides, so baseline 3 applies.

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

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

The description states a specific resource ('the fleet roster') and scope ('this node's live registry plus every other node's published snapshot'), and the fields it exposes (observedOn, alsoOn, coverage) make the intent clear. It doesn't name a specific sibling to differentiate from, but the roster/presence framing is distinct enough to be actionable.

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

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

The description implies when to use it — checking presence before believing an absence, reading coverage/blindTo before concluding a node is dead — but there's no explicit when/when-not or sibling alternative named. The vivid anti-pattern example (escalating a worker as dead four times) conveys the intended context indirectly rather than stating a 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 burden and discloses important behavior: the storage path, the append action, and the delivery semantics including mesh-synced peers. It doesn't cover permissions, idempotency, or failure modes, but the core behavioral 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?

Two sentences: the first states the action and location, the second states the delivery behavior. It's front-loaded, information-dense, and has no filler.

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

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

The description covers what happens, where it happens, and how delivery works, which is sufficient for a simple queue write. It doesn't mention return/error behavior, but the absence of an output schema makes that less critical here.

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

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

The schema already covers 75% of parameters with descriptions, including role, from, and task. The description adds little beyond calling the payload a 'message,' so it doesn't materially improve parameter understanding 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?

The description uses a specific verb ('Append') and resource ('a role's queue') while also naming the delivery target and the file path. This clearly distinguishes the tool from siblings like hub_queue_wait, which consumes messages.

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

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

It explicitly frames the tool for cross-agent/cross-node handoffs and explains that messages go to whoever calls hub_queue_wait. It doesn't mention alternative tools for other messaging patterns, but the context is clear enough for selection.

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

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

With no annotations, the description fully carries the burden: it discloses blocking behavior, timeout return value ({changed:false}), task id handling, the obligation to report outcomes onto tasks, and the local-only deployment constraint. The timeout rationale is also transparently explained.

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

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

The description is compact but comprehensive, with every sentence contributing essential context: the long-poll nature, return value, task edge case, deployment constraint, and usage alternative. No fluff or repetition.

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?

Even without an output schema, the description covers return values, timeout behavior, special task handling, and the correct usage scenario. It is complete for an agent to determine when and how to invoke this tool.

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

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

The description adds meaning to the 'role' parameter by explaining it as the queue's subject ('role's queue'), which the schema lacks. The 'timeout' parameter is already well-described in the schema, so the description appropriately references it without redundancy. This compensates for the 50% schema coverage.

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

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

The description clearly states the tool blocks until new content arrives in a specified role's queue and returns it, describing it as a 'real long-poll, not a snapshot you have to re-poll.' This verb+resource+mechanism structure distinguishes it from sibling tools like hub_queue_send and hub_queue_wait_all.

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?

Explicit guidance says 'Use this instead of a sleep-and-recheck loop when waiting on an agent to report back via hub_queue_send,' and notes the local/stdio-only availability. It also references hub_queue_send for task semantics, giving clear context on when to choose this tool.

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

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

With no annotations provided, the description fully carries behavioral disclosure. It explains blocking behavior, return shapes on both success and timeout, that it uses its own offset bookkeeping, and critically that it 'does NOT consume/steal messages' — a key non-destructive trait. It also states the 'Local/stdio only' restriction, providing complete behavioral context.

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

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

Four sentences deliver maximum substance with zero filler. Each sentence serves a distinct purpose: what it does, when to use it, what it returns, and its non-consuming behavior. The most critical action phrase is front-loaded, and the content is well-structured.

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?

Despite having no output schema, the description fully documents the return values ({changed, events} with role/node tagging, or {changed:false}). It also covers timeout semantics, non-destructive behavior, and platform restriction. For a tool with one parameter and no output schema, this is 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 coverage is 100% for the single timeout parameter, and the schema already documents the default (45), max (540), and the client-timeout caveat. The tool description adds behavioral context about blocking and timeout returns, but does not need to elaborate the parameter syntax, so the baseline score of 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'Subscribe to EVERY role's queue at once and block until new content lands in ANY of them.' It clearly distinguishes this tool from the sibling hub_queue_wait by explicitly saying 'instead of calling hub_queue_wait per role.' The purpose is unambiguous and unique.

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

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

It gives a concrete use case ('for an orchestrator reacting to whichever agent reports first') and names two alternatives it replaces ('instead of calling hub_queue_wait per role or ssh-ing into each host to poll'). This is explicit guidance on when to use this tool versus others.

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: it discloses the deterministic ranking stages (term coverage, line provenance, recency), the staleness mechanism with its resulting 'stale' flag, and the tool's real failure mode (old facts presented with fresh confidence). This is unusually rich behavioral context.

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

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

Front-loaded with the purpose, then scoring, then staleness. Efficient overall, though the closing failure-mode sentence is a narrative flourish that is a touch long for a tool definition.

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, so the description must convey the return shape; it explains that every hit carries an as-of date and a stale flag, and the schema covers truncation. It stops short of describing the full hit structure, but is sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents query tokens, full/limit/project/staleDays behavior and the truncated/dropped reporting. The description adds no parameter detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource — recall what the hub 'knows about X' — and enumerates the ranked sources (project cards, sections, decisions, journal, tasks), explicitly contrasting with both hub_search and hub_get. An agent can distinguish it from siblings 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?

Names two alternatives and their behaviors: hub_search's 'flat exact-substring list' and hub_get's 'everything-about-one-project'. The condition that selects this tool (wanting ranked, relevance-ordered recall) is clear from the contrast.

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 provided, so description carries full burden. It only states the action without disclosing behavioral traits like idempotency, error handling, or prerequisites. Essential details missing.

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

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

The description is a single, efficient sentence with no superfluous words. It front-loads the purpose and parameter pattern clearly.

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

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

Given no annotations, no output schema, and 4 parameters, the description lacks context on what a soft-lock is, return values, or error conditions. It is insufficient for an agent to fully understand the tool's behavior.

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

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

Schema description coverage is 0%, so description must add meaning. It explains that 'id' is an alternative to 'project+area+agent', adding some structure. However, it does not clarify individual parameter meanings (e.g., what 'area' or 'agent' represent), leaving gaps.

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

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

The description clearly states 'Release a soft-lock,' which is a specific verb and resource. It also provides alternative parameter combinations, distinguishing it from siblings like hub_claim (acquire a lock) and hub_get (read).

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

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

The description implies when to use (to release a soft-lock), but does not explicitly exclude scenarios or compare with alternatives. It is clear enough for an agent to infer usage context.

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

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

No annotations exist, so the description carries the full burden and largely declines it: it says 'append' but nothing about whether entries are synced, whether they are mutable, required permissions, or what the response returns. Non-trivial behaviors like the local-only 'private' braid and the 'NEXT:' card replacement live only in the schema, not the prose.

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

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

A single terse, front-loaded sentence with zero waste. It is efficient, though arguably it is so short that it under-serves a 7-parameter tool rather than being optimally sized.

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

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

The tool has real complexity (force refusals, private local-only routing, stale-digest hints, card NEXT: semantics) and neither annotations nor an output schema to lean on, yet the description conveys none of it. An agent could invoke it but would not understand the side effects that the schema hints at only partially.

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 57%, so the schema documents about half the parameters. The description contributes only the done/broken/blocked framing that maps loosely to the 'kind' enum and adds nothing about force, private, or staleDays semantics. A baseline 3 is appropriate given partial schema coverage and marginal prose value.

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 ('Append a session report to the shared journal') and the content it carries (done/broken/blocked). It is clear on its own, but does not distinguish itself from siblings like hub_card_set, hub_section_add, or hub_task_add, 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?

No when-to-use, when-not, or alternative routing is given. The phrase 'session report' weakly implies end-of-session summarization, but with many overlapping journaling siblings the agent receives no signal about why to pick hub_report over hub_card_set or hub_task_add.

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 should disclose behavioral traits but only states what is returned. It does not mention read-only nature, authorization needs, or error handling (e.g., if slug is invalid).

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

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

The description is a single sentence with no wasted words, front-loading the key content. However, its brevity sacrifices completeness, but it remains 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?

Given the lack of output schema and annotations, the description is too sparse to fully inform the agent. It does not cover return format, parameter semantics, or how to handle common scenarios, especially with many sibling tools.

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

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

The input schema has a single required parameter 'slug' with no description, and the tool description does not explain its purpose or format. Schema coverage is 0%, so the description fails to add any meaning.

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

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

The description clearly specifies that it retrieves one resource card along with its inbound and outbound typed relationships, which is specific and distinguishes it from sibling tools like hub_resource_list (list) or hub_get (generic).

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

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

No guidance is provided on when to use this tool versus alternatives such as hub_resource_list or hub_get. The description does not mention any conditions, prerequisites, 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?

With no annotations provided, the description carries the full burden, but it only states the core list behavior. It does not disclose the output format, default truncation behavior, or pagination; these are partially covered by the `full` parameter's schema description, but the tool description itself does not mention them. The read-only nature is implied by 'List', but no explicit safety or side-effect context is given.

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

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

The description is a single, focused sentence that immediately states the action and the resource with parenthetical examples. There is no redundancy, filler, or unnecessary detail—every word 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?

The tool is simple (2 optional params, no output schema, no annotations), and the description covers the basics. However, it omits any mention of the default behavior of truncating long lists (which is only in the parameter schema) and gives no pointers to when to choose this over similar tools. For a minimal list tool it is acceptable but not comprehensive.

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

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

The schema has 50% coverage: `full` is described, `type` is not. The description's phrase 'Optionally filter by type' adds meaning to the `type` parameter and provides examples of possible values in parentheses. However, it does not elaborate on the `full` parameter, which is already covered by the schema, so the description only partially compensates for the missing 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 description uses a specific verb 'List' and a resource ('resource cards') with examples of included types (hosts, vms, services, endpoints, providers). This clearly differentiates it from siblings like hub_resource_get or hub_resource_set, as it is about enumerating multiple entities rather than fetching or updating a single one.

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

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

No explicit guidance is given for when to use this tool versus alternatives. It does not mention alternatives such as hub_resource_get or hub_search, nor does it specify any exclusions or prerequisites. The 'optionally filter by type' note is about parameter usage, not usage context.

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

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

With no annotations, the description carries the transparency burden. It discloses the mutating nature ('Create or update') and states that structured attributes and typed relationships 'go in fields, NOT prose,' which clarifies the expected input format. However, it does not disclose idempotency, partial update semantics, error cases, or impact on existing edges (though the schema notes edges are merged). This is adequate but not rich.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause earns its place. It wastes no words and immediately clarifies the resource category and formatting requirement.

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

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

For a 9-parameter tool with a nested object and no output schema, the description provides enough context to know whether to invoke it and what kind of resource to create or update. It does not detail return values or error handling, but those are not critical for a setter. The mention of 'NOT prose' and the explicit list of resource types makes it functionally complete for agent selection.

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

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

The input schema already documents 89% of parameters with meaningful descriptions (e.g., slug as resource id, edges as typed relationships). The description names some attributes (type, address, os, provider, status) that map to schema properties, but adds no new semantics beyond emphasizing that they belong in fields rather than prose. This is baseline for high schema coverage.

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 'Create or update a resource' clearly stating the action, then defines the scope as 'infrastructure/topology entity: host, vm, service, endpoint, or provider' – a specific, identifiable resource class. This distinguishes the tool from sibling read tools like hub_resource_list and hub_resource_get, and from other hub_* tools.

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

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

The description gives explicit guidance to use this tool instead of 'describing infra inside a card digest' and emphasizes structured fields over prose. It clearly defines when this tool is appropriate, though it does not explicitly contrast with sibling read tools or mention any exclusions beyond the card digest comparison.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It reveals the append-only nature, the dated/attributed heading requirement, and the destructive consequence of rewriting (destroys the record hub_audit needs to quote). This is thorough and sets clear expectations.

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 sentences, front-loaded with the core purpose. The subsequent sentences about HUBD.md and append safety are relevant and non-redundant, each earning its place without unnecessary fluff.

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

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

For a simple two-parameter tool with no output schema, the description covers the main operations and constraints well. It explains what appending does and why rewriting is bad, but doesn't explicitly state what reading returns, which is inferable but not directly specified.

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

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

The input schema already describes both parameters well (100% coverage). The description adds meaning by clarifying that 'append' must be one line and that 'by' corresponds to the attributed heading, reinforcing the append format beyond the schema's brief notes.

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

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

The description clearly states the tool's purpose: read or append an amendment to the team constitution (AGENTS.md). It distinguishes itself from sibling tools by emphasizing this is the rules file where user-set rules live, contrasting with generated HUBD.md for hubd mechanics.

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 explicitly says when to use the tool ('read it, or append an amendment') and provides a key constraint (never rewrite existing lines). It references hub_audit to explain the importance of the append-only behavior, but doesn't explicitly name alternative tools for other purposes, keeping it just short of a 5.

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

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

With no annotations, the description carries the burden. It discloses the search scope (every card, entire journal, archived months), the return format (matching lines with location), and implicitly that it is a read-only operation. It does not mention truncation behavior or performance, but the schema's `full` parameter covers the truncation detail, and there is no destructive behavior to disclose.

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 sentences, each earning its place: the first states purpose, the second provides usage guidance, the third adds an additional use case. No filler or redundancy.

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

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

For a simple 2-parameter read-only search tool with no output schema, the description covers what, when, and why. It differentiates from siblings and explains the scope. The only minor omission is a note about truncation, but that is handled by the schema, so the description is complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving example query types ('a keyword, a task id or a name') and clarifies that the search is full-text, which goes beyond the schema's plain 'case-insensitive substring' 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: 'Full-text search across every project card and the entire journal, archived months included.' It clearly states the return value ('each matching line with its location') and distinguishes itself from hub_task_list by explaining that search is the right approach when you know a keyword but not the owning project.

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?

Explicit guidance is given: 'START HERE whenever you know a keyword, a task id or a name but not which project owns it.' It directly names the alternative (hub_task_list) and explains why searching once is better than guessing, plus adds a second use case ('find where something was discussed or decided').

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 of behavioral disclosure. It discloses that content is appended without disturbing existing content, that sections are created if missing (returning created:true), and warns about the risk of typo-induced duplicate headings. However, it does not mention the mode=set replacement behavior, which is only described in the schema, leaving a notable behavioral 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?

The description is dense but efficiently structured: the first sentence states the core action, the second provides usage guidance, and the third warns about a common pitfall. Every sentence earns its place, with no filler or repetition of structured data.

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 no output schema and six parameters, the description covers the essential context: core purpose, scenarios, side effects (creation, non-destructive), and a warning. It could further explain the mode=set behavior and the full return structure, but these are partially covered by the schema, so the description is reasonably 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 high (83%), so the baseline is 3. The description adds meaningful context for the 'section' parameter by enumerating typical values (Gates, Metrics, Market) and clarifying which sections are not appropriate (the four report sections). It also reinforces the 'one line' constraint for text, adding value 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?

The description begins with 'Append ONE line to ONE section of a project card...' which clearly specifies the action and target. It further distinguishes itself from siblings by explicitly contrasting with hub_card_set and hub_report, making the tool's unique purpose unmistakable.

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

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

The description explicitly states when to use this tool (for Gates / Metrics / Market and any hand-written section) and when not to (for Decisions / Facts / Communication / Next step, where hub_report should be used). It names alternatives directly, providing clear selection guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses a subtle behavioral nuance: a card can appear fresh while its digest is stale, represented by digestStale with daysBehind and lastJournal. Framing it as a 'snapshot' implies a read-only, point-in-time view. While it doesn't explicitly discuss side effects or authentication, it offers meaningful context beyond a bare description.

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

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

The description is compact and well-structured: it opens with the primary function, explains a key output nuance, then finishes with usage guidance. Each sentence contributes distinct value, and the length is appropriate for the tool's complexity.

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

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

Given that there is no output schema, the description usefully enumerates the response contents (digest, last sync, open-task count, journal entries) and even the digestStale field shape. It covers usage context and alternatives, making it functionally complete. A more detailed return-type spec would be nice, but it is adequately complete for an orienting snapshot tool.

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

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

The input schema already describes both parameters (full and staleDays) with 100% coverage, including the trimming behavior and default stale threshold. The description adds no additional parameter meaning, so the baseline for high schema coverage applies.

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

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

The description clearly states what the tool does: it provides a 'Snapshot of every project at once' with digest, sync time, open-task count, and recent journal entries. It uses a specific verb and resource and distinguishes itself from hub_brief and hub_get, making its purpose unambiguous.

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

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

The description explicitly says 'Best for orienting at the start of a session' and points users to hub_brief for deadline-sorted lists and hub_get for in-depth project views. This provides both the ideal use case and clear 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 provided, the description carries the full burden. It discloses that git facts are collected automatically and that the card is rewritten, which is useful context. However, it omits potential side effects (e.g., overwriting existing card content), failure modes, or permission requirements.

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

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

The description is two sentences long and directly packed with meaning. No filler words or redundancy; every clause contributes to understanding the tool's function and required input.

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 relatively simple tool with four parameters and no output schema, the description covers the core behavior and needed inputs. A minor gap is not stating what the tool returns or what 'rewritten' implies (e.g., full replacement vs. merge), but this is not critical for basic usage.

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

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

The input schema already documents all four parameters thoroughly (100% coverage), so the description does not need to add much. The mention of 'digest' reinforces the agent-written summary parameter, but it adds no semantics beyond what the schema already provides.

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

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

The description clearly states a specific verb ('Sync') and resource ('project folder into the hub'), and adds key behavior (collects git facts, rewrites the card). This distinguishes hub_sync from the many other hub_* 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?

It implies when to use the tool by explaining that you pass a digest and the card is rewritten, which suggests use when updating the hub card with current project state. It does not explicitly name alternatives or say when not to use it, so it falls short of a 5.

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

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. 'Add' implies a mutation, but the description does not disclose permissions, side effects, duplicate handling, or any other behavioral trait beyond the basic write intent.

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

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

The description is a single front-loaded sentence that states the core action without any wasted words. Its brevity is appropriate for the amount of information it conveys.

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 mutation tool with no annotations and no output schema, a one-line description is too thin. It omits usage guidance, behavioral context, and any mention of return values or side effects, leaving significant gaps for an agent to fill.

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 82%, which is high enough that the schema does most of the work in explaining parameters such as 'by', 'cat', 'tags', and 'verbose'. The description itself adds no parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb and resource: 'Add a task to the shared cross-project backlog.' It clearly identifies the action and the target collection. However, it does not explicitly differentiate itself from siblings like hub_task_update or hub_task_get, relying on the verb 'Add' alone for 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?

The description gives no guidance on when to use this tool versus alternatives such as hub_task_update or hub_task_list. It does not state prerequisites, context for the shared backlog, or conditions that would select this tool over a sibling.

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

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

With no annotations, the description carries full burden. It discloses the return content (task plus blocked-by/blocks) and conveys a read-only behavior. It could add what happens if id not found, but the essential behavioral trait is 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?

Two sentences, front-loaded with purpose, then clear usage direction. No filler; every sentence adds value.

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

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

For a simple one-parameter getter without output schema, the description sufficiently explains what is returned and when to use it. It is complete enough for an agent to invoke correctly, though it does not cover error behavior, which is a minor gap.

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

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

Schema covers 100% of the single parameter with description and type. The description adds no extra parameter info beyond reinforcing that the id must be known, but with full schema coverage a baseline of 3 is appropriate.

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

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

Description clearly states the tool fetches a single task by id and includes its blocking relationships. It explicitly distinguishes from sibling hub_task_list and provides context for when to use this tool over alternatives.

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 'Use this when you know the id' and warns against guessing combinations with hub_task_list. It also directs users to hub_search for keyword-based lookup. This gives strong when/when-not guidance.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds valuable context that `total` always reflects the full matching count, so a page never reads as the whole backlog—a subtle but important behavioral nuance. It does not explicitly state side-effect safety, but the read-only nature of listing is strongly implied and no destructive hints are needed.

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

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

The description is three sentences with zero filler. It front-loads the action, then delivers the critical pagination caveat, then names alternatives—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?

The description covers purpose, filters, paging semantics, and alternative tools, which is strong for a simple list operation with no output schema. Minor gaps remain: no mention of default page size or what fields appear in the returned tasks, but these are not critical for tool selection and invocation.

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

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

Schema coverage is 60%, and the description compensates by explaining how the parameters work together: 'Filter by project and/or status; page with limit/offset.' It also clarifies pagination semantics with the `total` remark, adding meaning beyond the schema's bare parameter descriptions. It doesn't cover `full` in detail, but the schema already describes that adequately.

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+resource ('List backlog tasks') and immediately distinguishes itself from siblings by naming hub_task_get and hub_search as better alternatives for finding a single named task. It also covers the key filtering and paging capabilities, making the tool's purpose unmistakable.

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

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

Explicit usage guidance is present: filters are listed ('project and/or status'), paging is mentioned ('limit/offset'), and a clear exclusion is given—'Looking for ONE task you can name? hub_task_get by id, or hub_search by keyword—both beat listing and scanning.' This tells the agent exactly when to avoid this tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that 'update' includes closing, reassigning, reprioritising, and editing text/deadline/cat, but it does not disclose whether updates are partial or full replacements, side effects on related resources, required authentication, or what the response contains. This is a significant gap for a mutation tool with 11 parameters.

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

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

The description is a single sentence of 13 words, front-loaded with the action 'Update a task'. Every word contributes to purpose and capabilities, with no filler or repetition. It efficiently covers the core functionality without unnecessary detail.

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

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

For a tool with 11 parameters, no annotations, and no output schema, this description is too minimal. It fails to mention the required 'by' parameter, whether updates are partial or full, what happens to unspecified fields, return values, or any side effects. Given the complexity, the description leaves substantial gaps in the information an agent would need to invoke 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?

The schema already describes several parameters (cat, tags, resources, depends_on). The description adds meaning to some parameters (e.g., 'close it' maps to status, 'reassign' maps to assignee, 'reprioritise' maps to importance) but does not significantly elaborate on parameter semantics beyond what is in the schema. It groups capabilities but offers little additional detail for parameters like id, by, text, and deadline.

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 the specific verb 'Update' with the resource 'task' and enumerates concrete actions: close it, reassign, reprioritise, edit text/deadline/cat. This clearly distinguishes it from sibling tools like hub_task_add, hub_task_get, and hub_task_list, which handle creation, retrieval, and listing respectively.

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 usage when a task needs modification, but it provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or contrast with sibling tools like hub_task_add or hub_task_get, leaving the agent to infer the appropriate context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and largely succeeds. It states the tool is deterministic ("not an ML forecast"), explains what each return field means, and reveals a limitation: "Weight is task-count now; weighted by real durations once logd records them." While it doesn't explicitly declare read-only or side-effect-free behavior, the "Returns:" phrasing implies a safe query 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 description is concise and well-structured: it leads with the core purpose, lists return values, provides a use-case sentence, and then notes the current weight limitation. Every sentence adds value, and the length is appropriate for the tool's complexity—no redundancy or filler.

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

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

The tool has no output schema, so the description's explanation of each return field (ready, blocked, layers, criticalPath, cycles) is essential and provided. It also covers the deterministic nature and current weight behavior. The main omission is an explicit statement about permissions or side effects, but the description and schema together give a fairly complete picture for a read-only analysis tool.

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

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

The input schema covers 100% of parameters (full and project), each with a clear description. The tool description itself adds no extra parameter semantics, but the schema already provides adequate meaning, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: "Deterministic dependency-graph plan over tasks' depends_on". It clearly distinguishes itself from an ML forecast and enumerates the exact outputs (ready, blocked, layers, criticalPath, cycles), making its purpose unmistakable and differentiating it from sibling tools like hub_graph or hub_next.

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 provides an explicit use case: "Use to see 'given deps, what is the actual order / what is the critical path to a milestone'." This is clear context for when to invoke the tool, though it does not mention when not to use it or name alternative tools, which would make it fully explicit.

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

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

No annotations are provided, so the description must disclose behavior. It explains the conceptual split between SUPPLIED (client-reported) and MEASURED (hub-derived) data and warns against mixing them. This provides meaningful behavioral context beyond just saying 'returns usage'. However, it does not specify return format or whether agent/project filter the results, so it is not fully transparent.

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

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

The description is two sentences and front-loads the purpose. The second sentence adds important nuance about the supplied/measured split and the warning. No unnecessary words.

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

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

With no output schema and no annotations, the description should cover return structure and default behavior. It explains the core concept but does not mention the default window of 7 days (though the schema hints at it) or what the response looks like. It also does not clarify behavior when agent/project are omitted.

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

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

Schema coverage is only 33%, with only 'days' having a description. The description adds meaning by mapping 'days' to the window and suggesting 'agent' and 'project' are grouping dimensions. It does not explicitly clarify whether agent/project are optional filters or always part of the grouping, leaving some ambiguity.

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

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

The description clearly states the tool reports work cost over a time window, aggregated per project and per agent. It distinguishes from hub_usage_add by explaining that SUPPLIED data comes from clients via that tool. This gives a specific verb+resource and differentiates from the 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 this is the read counterpart to hub_usage_add by noting that clients report supplied data through that tool. It does not explicitly state when to use this tool vs alternatives, but the contrast between SUPPLIED and MEASURED gives context. There is no explicit exclusion or when-not-to-use, 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?

The description discloses important behavioral traits: reported values are tagged as SUPPLIED and never mixed with hub-measured data, and an empty entry records a $0 session. With no annotations provided, this detail is valuable.

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

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

Two sentences, front-loaded with the action and resource, every sentence adds meaningful information. No fluff.

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

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

The description covers the core purpose and key semantics, but for a tool with 8 parameters and no output schema, it lacks details on return values and full parameter meanings. It's adequate but has 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?

The description names some parameters (seconds, tokens, cost, model) and adds a cross-field constraint, but it doesn't explain all eight parameters or the tokensIn/tokensOut distinction. Given 0% schema coverage, this is 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 clearly states the tool's function: recording usage metrics (seconds, tokens, cost, model) that only the user can observe. It distinguishes itself from sibling tools by emphasizing that data is supplied explicitly because the hub cannot measure it.

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

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

It provides context for when to use the tool—whenever you have usage data the hub cannot observe—and includes a validation rule (at least one number required). However, it doesn't explicitly name alternatives or exclusions, so it earns a 4 rather than 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?

No annotations are provided, so the description carries the full behavioral burden, and it does substantial work: read-only / files nothing, per-agent-name checkpoint tracking, default trimming with a `truncated` report, and the review block contents. It does not mention permissions or rate limits, but for a pure-read tool this is close to fully disclosing its behavior.

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 identity/mode of the tool comes first, then the differentiation from siblings, then the review payload. A few clauses are packed with parentheticals that make a single paragraph slightly heavy to parse, but no sentence is wasted.

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

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

There is no output schema, so the description must convey the return shape, and it does: journal activity plus a `review` block of top hub_lint/hub_audit findings, one per kind, each quoting its rule and date, with truncation reported. The only gap is that the shape of the journal entries themselves is not described.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning beyond the schema for the critical `since` parameter (checkpoint vs session vs ISO, and when each applies) and explains the interaction between checkpoint movement and `project`/`hours`. This is more than restating the schema, though not every parameter gets extra context.

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 and unusual verb+resource ('personalized what did I miss — journal activity since your own last call') and explicitly distinguishes it from hub_brief ('not a fixed time window like hub_brief') and hub_status. An agent can tell exactly what this returns and how it differs from its closest siblings.

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

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

Gives explicit when-to-use guidance ('call this at the start of a session/sweep instead of re-reading hub_status/hub_brief from scratch') and names the alternative it replaces. It also covers the edge case of a first-time agent (24h window) and which `since` mode to use after a context compaction.

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