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 fully carries the transparency burden. It discloses subtle behavioral details: the distinction between stale and staleDigests (misleading kind), broadcast roles being flagged as fanout instead of depth (per-reader cursors), and the truncation behavior with the `truncated` field. This goes beyond basic read-only and explains edge cases.

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 long run-on sentence with multiple semicolons, making it hard to parse. It is not well-structured or front-loaded; the many components could be bulleted for readability. Though every clause contains useful info, the format undermines conciseness.

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

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

There is no output schema, so the description carries the burden of explaining the return content. It lists all major components and covers truncation details and special cases. It could mention permissions or error handling, but for a read-only brief it is fairly 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% and each parameter already has a descriptive explanation ('return everything, uncapped', 'journal window, default 48', etc.). The description adds minimal extra meaning beyond what 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 the tool produces a 'Morning brief across all projects' and enumerates its specific contents (open tasks, stale cards, active claims, queue depth, buttons rollup). This specific verb+resource scope distinguishes it from sibling tools like hub_report 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 provides clear context that this is for a morning overview across all projects, with no explicit exclusions or alternatives. It does not name sibling tools but the scope is well-defined, so the agent can infer when to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses the upsert nature ('Create or update') and the preservation of hand-written frontmatter and Facts, which is valuable. However, it does not mention return format, error handling, permissions, or whether other fields are overwritten, leaving some behavioral 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 three sentences with no redundant wording. It front-loads the core purpose, then adds usage context and a key behavioral guarantee, making it highly efficient and 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?

For a simple 3-parameter tool with no output schema, the description covers the primary purpose, when to use it, and a notable behavior (preserving frontmatter/Facts). It stops short of describing return values or edge cases, but the provided context is sufficient for an AI agent to select and invoke the tool correctly in typical scenarios.

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 extra semantics for 'project' by noting 'no folder needed' and implies 'digest' is the current state via 'a name and a digest', but does not elaborate on the 'by' parameter, which is fully covered by the schema's existing 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 clearly states the tool's action ('Create or update a project card') and its key inputs ('name and digest'). It explicitly differentiates from sibling hub_sync by noting 'no folder needed', and provides a concrete example use case ('when harvesting a dialog'), making the 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?

It gives explicit usage guidance: 'Use it to capture a project that is not a local git checkout' and names the alternative tool (hub_sync) with a contrast ('unlike hub_sync'). The example of harvesting a dialog further clarifies when to choose this tool over siblings.

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

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

With no annotations, the description carries full burden. It reveals the soft-lock is not enforced, but lacks details on conflict handling, idempotency, or effect of repeated claims. Some transparency but incomplete.

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?

Single sentence, front-loaded with action and purpose, no wasted words. Efficiently communicates core functionality.

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 claim tool, the description covers essential purpose but omits details like return value, duration semantics (despite ttlMin having a default), and whether lock is replaceable. Adequate but not thorough.

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 20% (only ttlMin has description). The description mentions 'area' in example but does not explain note, agent, project, or ttlMin's behavior beyond default. Insufficient compensation for low 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 verb 'soft-lock' and the resource 'work area' with a concrete example. It distinguishes from sibling tools which are all non-locking operations like hub_get, hub_search, etc.

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

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

The description explains the tool is informational and not enforced, giving context for when to use it. However, it does not explicitly state when not to use it or mention alternatives, though uniqueness among siblings makes that less critical.

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

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

With no annotations, the description carries the full behavioral burden and does so well. It discloses the exact lookup priority (.hubd marker, sync path, folder name guess), the guessed:true flag, the refusal to silently trust name coincidences, and the null-with-hint failure mode. This goes beyond a generic 'resolves project' statement.

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 action and usage, then uses a compact bullet-style list for resolution order and return fields. Every sentence/segment adds essential information—no filler, no repetition of the schema.

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

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

Given there is no output schema and no annotations, the description must explain both behavior and return shape. It enumerates the return fields ({project, via, root, guessed, digest, openTasks, activeClaims}) and covers the failure case. The combination of when, how, and what happens makes the tool fully usable without external references.

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

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

Schema description coverage is 100% and the cwd parameter already has a thorough explanation ('Absolute path to YOUR OWN current working directory — this cannot be inferred...'). The description only echoes this by saying 'when you already know your cwd,' adding no new parameter-level meaning, so the 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?

The description uses a specific verb ('Auto-resolve') and clearly identifies the resource (hub project from the current working directory). It explicitly contrasts with sibling tools hub_status/hub_get, stating this is for when you already know your cwd, making the purpose distinct.

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 explicit when-to-use guidance ('call this at session start instead of hub_status/hub_get when you already know your cwd') and names the alternative tools. The resolution-order explanation also frames when the fallback naming heuristic applies, giving the agent practical decision rules.

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?

No annotations are provided, but the description discloses key behavior: it 'overwrites this agent's one presence record' and explains freshness is evaluated at read time using ttlMin with a default of 15 minutes, aligning with hub_claim. This is critical side-effect information not visible 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?

The description is two sentences that pack the purpose, scheduling, and key behavioral details without redundancy. It is front-loaded with the main action and uses the second sentence to cover overwrite and ttl 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 heartbeat tool with no output schema or annotations, the description covers purpose, when to call, why, and core behavior (overwrite, TTL). It omits return values and error cases, but these are less critical for this simple write-like operation; overall it's robust.

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 6 parameters have descriptive schema entries (100% coverage), so the description need not repeat them. It adds minor context by mentioning the ttlMin default and read-time evaluation, but the schema already includes a similar description. Therefore, 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?

The description opens with 'Record that an agent is alive,' a specific verb and resource. It distinguishes this from siblings by contrasting with hub_presence (where the heartbeat appears) and by positioning it in the agent work cycle relative to hub_report and hub_queue_wait.

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 scheduling guidance: 'call it each work cycle (right after hub_report, before the next hub_queue_wait)'. It also explains why: to let MCP/headless agents appear in hub_presence without a human bridge, which implies when it's needed versus not.

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 provided, the description carries the burden of behavioral disclosure. It explains the tool is an orientation (informational, not state-changing) and that it should be called first. However, it does not explicitly state side effects (e.g., 'does not modify any data'), but the nature of orientation strongly implies a safe, read-only 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?

A single sentence that packs in all essential information: what the tool is, what it covers, and when to call it. No wasted words, and the key directive 'Call this FIRST' is front-loaded and prominent.

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 tool with no parameters, no output schema, and no annotations, the description is fully sufficient. It tells the agent all necessary context: what topic areas are covered, when to use it, and that it's a one-time prerequisite. The sibling list does not introduce ambiguity because this tool's role is clearly unique.

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

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

The tool takes zero parameters, so there is no parameter meaning to explain. The description fully compensates by explaining the tool's content and purpose. The baseline score of 4 for zero-parameter tools 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 is a one-time orientation for agents new to the hub, covering hubd basics, channel usage, and report writing. This distinguishes it from sibling tools like hub_claim or hub_report, which perform specific actions. The verb 'orientation' and phrase 'Call this FIRST' make the 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?

Provides explicit usage guidance: 'Call this FIRST, before anything else, the first time you connect.' This tells the agent exactly when to use it and establishes precedence over all other tools. It also clarifies this is a one-time event, preventing redundant calls on subsequent connections.

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?

With no annotations, the description carries the burden of disclosing behavior. It explains the alive/stale derivation from ttlMin, which is useful. However, it does not explicitly state that this is a read-only operation or mention any side effects, permissions, or caveats like truncation (though truncation is in the schema). The description implies read-only but does not confirm it.

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

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

The description is concise, consisting of two sentences that efficiently convey the core purpose and a helpful pairing with hub_brief. The second sentence is slightly dense with the em dash and metaphorical language, but every phrase contributes valuable context.

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 tool's simplicity and full schema coverage, the description provides adequate context: it defines the roster, the alive/stale flag, and how it integrates with hub_brief. It does not detail the output format, but without an output schema, the description's high-level overview is sufficient for this read-only listing tool.

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

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

Schema coverage is 100% for the three parameters, so the schema already documents them fully. The description does not add any parameter-specific meaning; it only mentions ttlMin, which relates to the live/stale concept rather than any input. Thus, the description adds no value beyond the schema, warranting the baseline score.

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 defines the tool as a fleet roster of agents that have called hub_heartbeat, with alive/stale status based on ttlMin. It uses a specific verb+resource construction and distinguishes itself from sibling tools like hub_heartbeat (the act of beating) and hub_brief (queue info).

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 clear context: it is for checking who is listening/active, and explicitly pairs with hub_brief's queue section. However, it does not explicitly state when to prefer this over alternatives or mention exclusions, so it stops short of full 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 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 excels: it reveals deterministic scoring logic (term coverage, line location, recency), discloses that every hit carries a date-as-of and a stale flag, and even names the failure mode of stale facts. This goes well beyond typical descriptions.

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, then contrasting alternatives, then detailing ranking and output. Every sentence contributes essential information with no waste, making it well-structured and efficiently 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?

Despite no output schema, the description sufficiently explains the return semantics (ranked hits with dates and stale flags) and covers purpose, alternatives, and scoring. For a moderately complex tool with a good input schema, this description provides enough context for an agent to select and invoke 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?

The input schema covers 75% of parameters with descriptions (full, limit, staleDays), and the description adds semantic context for staleDays by explaining the stale flag and date-as-of concept. It does not elaborate on query or limit, but the schema already handles those, so the description provides meaningful additional value without redundancy.

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: 'What do we know about X — ranked across project cards, their sections, decisions, the journal and tasks.' It distinguishes from siblings by explicitly contrasting with hub_search's flat exact-substring list and hub_get's everything-about-one-project, making its 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 gives explicit when-not-to-use alternatives: 'instead of hub_search's flat exact-substring list or hub_get's everything-about-one-project.' This implies the tool is for ranked, cross-source recall and directly names the alternatives, satisfying the 'explicit when/when-not/alternatives' criterion.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'shared journal' but omits critical details like persistence, sync implications, permissions, and the private/local routing behavior. The agent is left unaware of important side effects beyond the basic append action.

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, front-loaded with the action, and contains zero filler. Every word adds value, making it highly concise and scannable.

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 5 parameters, no output schema, and no annotations, the description is too sparse. It doesn't explain the return value, how to use the private parameter, or the meaning of required fields, leaving the agent with insufficient context 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 low (40%), and the description only echoes the enum values (done/broken/blocked) already present in the schema. It adds no clarity for the required parameters (project, agent, text) or the private flag's nuanced routing behavior, failing to compensate for the coverage gap.

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

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

The description clearly identifies the action ('Append') and the resource ('session report to the shared journal'), and specifies the content categories (done/broken/blocked). This distinguishes it from sibling tools like hub_card_set or hub_section_add, which handle different data forms.

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 for logging session outcomes but provides no explicit when-to-use guidance or exclusions. It doesn't mention alternatives or clarify when to choose hub_report over other write tools, such as hub_task_add or hub_queue_send.

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 must carry the full behavioral burden. It merely says 'Add a task' without disclosing side effects, permission requirements, idempotency, or return format. The added context 'shared cross-project backlog' clarifies scope but not 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 a single sentence, front-loaded with the verb and object, and every word contributes. There is no fluff 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?

Given 10 parameters, a write operation, and no annotations or output schema, a single sentence is insufficient to fully orient the agent. The rich schema descriptions help, but the description omits usage conditions, return behavior, and relationship to sibling task tools.

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

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

Schema description coverage is 80%, so the schema already documents most parameters. The description itself adds no parameter-level detail beyond what the schema provides; per rubric, high coverage yields a baseline of 3.

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 action — 'Add a task' — with a clear resource ('shared cross-project backlog'), distinguishing it from read/update task siblings like hub_task_list, hub_task_get, and hub_task_update. The scope is explicit and not 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 given on when to use this tool versus alternatives, no exclusions are mentioned, and sibling tools are not referenced. The single sentence provides only the core action without context 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 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 burden. It discloses the stateful tracking mechanism ('tracked per agent name') and the first-call behavior ('never-seen agent gets a 24h window'), which implies the tool maintains a checkpoint. However, it does not explicitly state that the call updates the checkpoint or describe any side effects beyond that, so a small transparency gap remains.

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, zero fluff. The first sentence front-loads the core purpose and differentiator; the second gives concrete usage guidance and an edge case. Every word earns its place, making it highly scannable.

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 stateful tool with no output schema, the description covers the essential context: what it does, when to use it, and the key behavioral nuance of per-agent checkpoints. It does not describe the return format, but the input schema's description of the `full` parameter mentions `truncated`, giving a hint. Given the tool's moderate complexity, this is nearly complete but not fully self-contained.

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 references 'per agent name' (agent) and '24h window' (hours), but these details are already fully documented in the schema parameter descriptions. No additional parameter semantics are provided beyond what the schema already offers.

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

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

The description states a specific verb+resource: 'journal activity since YOUR OWN last hub_whatsnew call'. It clearly differentiates from hub_brief by noting 'not a fixed time window like hub_brief', and from hub_status/hub_brief by recommending it as a replacement at session start. This is unambiguous and distinguishes among 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?

Explicit guidance is given: 'Call this at the start of a session/sweep instead of re-reading hub_status/hub_brief from scratch'. This tells the agent exactly when to use it and what not to use instead. The first-call fallback window is also explained, covering a key edge case.

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