hubd
Server Quality Checklist
Latest release: v0.9.14
- Disambiguation4/5
Most tools have clearly distinct purposes, and the descriptions are unusually good at calling out how each read/overview tool differs (status vs brief vs whatsnew vs inbox vs agenda). A few clusters, especially the read-oriented tools and hub_search vs hub_recall, could still cause misselection at a glance, but the distinctions are real and documented.
Naming Consistency3/5All names share the hub_ prefix and snake_case, which gives the set a recognizable identity. However, the naming style is mixed: some tools use resource_action (hub_task_add, hub_queue_send), some use bare nouns (hub_status, hub_brief, hub_inbox), and a few use noun_verb (hub_section_add, hub_card_set), so there is no single predictable convention.
Tool Count2/538 tools is well past the 25+ threshold and makes this a very heavy server surface. The scope is broad, covering cards, tasks, resources, queues, presence, usage, and rules, but the sheer count creates real navigation and discoverability overhead.
Completeness4/5The domain coverage is remarkably extensive: cards, tasks, resources, queues, claims, presence, reporting, usage, rules, search, audit, and lint are all represented with create/read/update operations. The main gap is the absence of delete/archive tools for projects, tasks, or resources, which may be intentional for an append-only hub but is still a lifecycle hole.
Average 4.2/5 across 38 of 38 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 85 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness2/5Given 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.
Parameters1/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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 thoroughly explains the data source, key fields (observedOn, alsoOn, coverage, blindTo/note), and the nuanced behavior that absence is not equivalent to death, backed by a concrete example. This exceeds typical transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose, including a lengthy anecdote that illustrates the tool's rationale. While the key information is front-loaded, the narrative adds length without directly aiding invocation. It is structured and readable, but not concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does well to explain the return data model (observedOn, alsoOn, coverage, blindTo/note) and the crucial interpretation caveat. It could be more explicit about the exact JSON shape, but it covers the essential context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters. The description adds some contextual meaning (e.g., role filtering in the anecdote) but does not materially enhance parameter understanding beyond the schema, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a fleet roster combining the node's live registry with other nodes' published snapshots. It differentiates itself from siblings by focusing on mesh-wide presence and the critical distinction between absence and death, giving it a specific, non-tautological purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides strong context for when to use the tool, emphasizing the need to read `coverage` before trusting absence and explaining the real-world pitfall of false dead alerts. However, it does not explicitly name alternative tools or state when NOT to use it, though the context implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It explicitly states 'It reports only', clarifies that nothing is filed without an explicit hub_audit apply, explains that review embeds hub_lint and hub_audit findings, and disambiguates subtle behaviors like staleDigests and per-reader cursors for broadcast roles. This fully compensates for the missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and a list of report contents, then adds necessary disambiguation of buttonItems versus ownerWaiting and the audit boundary. It is dense and somewhat run-on, but every sentence provides useful behavioral or conceptual detail rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only brief tool with no output schema and no annotations, the description is remarkably complete: it enumerates every major section of the result, explains truncation behavior, references configuration for owner queues, and clearly states the side-effect policy. An agent has enough context to invoke the tool and interpret the returned report without hidden surprises.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are already described in the input schema with clear meanings (full, hours, staleDays, reviewLimit), so the baseline is 3. The description reinforces concepts like reviewLimit being about finding kinds and full controlling truncation, but it does not add significant meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a concrete resource and behavior: a morning brief aggregating open tasks, journal entries, stale cards, claims, queue depth, buttons, and review findings across all projects. It is specific enough to be understood without opening the schema, though it does not explicitly name or contrast sibling report tools such as hub_report, hub_status, or hub_agenda.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong when/when-not guidance: it is a read-only morning rollup, and any intended filing or mutation requires an explicit hub_audit({apply:true}) carrying somebody's name. It also explains that the audit/review rides along on this call instead of waiting to be remembered, and distinguishes ownerWaiting from 'what can I start' lists, which helps the agent route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without any annotations, the description carries the full burden and does so excellently. It discloses the destructive overwrite behavior, the freshness semantics (judged at read time from ttlMin, default 15min, same pattern as hub_claim), the 5-minute throttle on the node snapshot refresh, and the node-local directory that never syncs. This is exactly the kind of hidden behavior that an agent needs to make correct consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences each carry active operational content: purpose and when, overwrite/timeout semantics, and a rarely surfaced cross-node refresh constraint. The core instruction is first in the lineup, and each sentence earns its place without filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six optional parameters and no output schema, the description provides all the practical facts required for a safe call: when to invoke it, what record is overwritten, how freshness is judged, and why a cross-node snapshot is needed. It also accounts for the asymmetric cross-node visibility issue, which is the most non-obvious piece of context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameters with detailed descriptions, so the description does not need to repeat them. It adds only minimal extra parameter-level meaning—ttlMin's freshness role and role's link to hub_brief—and even that mostly reiterates what is already in the schema. The description primarily enriches behavioral context rather than parameter definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first phrase, 'Record that an agent is alive,' uses a specific verb and resource, then sharpens the intent by placing it in an explicit call sequence: 'call it each work cycle (right after hub_report, before the next hub_queue_wait) so... show up in hub_presence.' This clearly separates the heartbeat tool from its more than 30 siblings, including hub_report, hub_presence, and hub_claim.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit context and a precise time to call the method: 'each work cycle (right after hub_report, before the next hub_queue_wait)' and explains the rationale for MCP/headless agents. It does not mention an explicit when-not-to-use case or list a competing alternative tool, so it falls short of a fully elaborated exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it succeeds: it discloses that the tool is read-only, files nothing, tracks per-agent checkpoints, uses a fallback window on first call, and returns a review block with one finding per kind, each quoting the rule and date. This is unusually transparent for a tool description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause carries meaningful information: what it returns, how the window is determined, when to call it, and what the review block contains. It is somewhat run-on, with many embedded clauses, but it remains readable and front-loads the core purpose before the alternatives and details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given 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 no annotations, this description provides enough context for correct invocation: the delta model, first-call behavior, return contents, review block semantics, and read-only guarantee. The agent knows what to expect and how this tool differs from its siblings. No critical information appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 adds value by explaining that agent is a stable identity reused across calls to compute the delta, and that review findings are limited to one per kind. This goes beyond the schema's bare parameter descriptions without duplicating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific function: returning journal activity since the caller's own last hub_whatsnew call, tracked per agent name. It explicitly differentiates itself from hub_brief (not a fixed time window) and positions itself relative to hub_status, so an agent can identify when this is the right tool. The verb is implicit but the resource and behavior are unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: call at the start of a session/sweep instead of re-reading hub_status or hub_brief from scratch. It also explains the first-call default (24h window), which prevents an agent from making wrong assumptions about deltas. This is strong contextual direction for when to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md: