Hermes Toolkit MCP

Overview Schema Related Servers Score Discussions

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation3/5
There is significant overlap in several areas: hermes_skill_patch_proposal vs hermes_skill_patch_apply are distinct, but hermes_skill_eval_start vs hermes_eval_start vs hermes_eval_run vs hermes_api_runs_start all involve 'starting evals/runs' and could be confused. Similarly, hermes_status_overview and hermes_toolkit_info and hermes_detect_install and hermes_config_summary all aggregate overlapping read-only metadata. The docs_list/docs_read pair for API and Kanban API are parallel but distinguishable. The naming clearly delineates domains (skill vs config vs api vs kanban vs eval), but within domains several tools have similar purposes the agent may struggle to distinguish.
Naming Consistency4/5
Tool names follow a consistent hermes_<domain>_<verb>_<noun> pattern throughout, using snake_case uniformly. The prefix structure is predictable (hermes_api_*, hermes_kanban_*, hermes_skill_*, hermes_eval_*), which helps agents navigate. Minor inconsistency: some use get vs read (hermes_api_models_list vs hermes_skill_read vs hermes_kanban_task_get), and _list vs _*_get conventions vary slightly, but the overall pattern is highly consistent and readable.
Tool Count2/5
73 tools is far above the typical well-scoped range of 3-15, and this is a very heavy surface. While the server has broad breadth (install, config, skills, API wrappers, Kanban, evals, jobs, gateway), 73 tools will impose substantial cognitive load on agents when selecting, and many could be consolidated (e.g., the read-only status/toolkit/info/detect aggregation tools overlap heavily, and the 7 jobs_* tools and 8 kanban_task_* tools could be trimmed). At 73, even with broad scope, this is too many.
Completeness4/5
Within the domains covered, there's strong lifecycle coverage: jobs have create/get/update/list/delete/pause/resume/run; Kanban tasks have create/update/get/comments/bulk/run_decompose; API responses have create/get/delete; runs have start/get/stop/events/approval. The addition of an agent_ask_fallback plus docs tools shows thoughtful coverage. Minor gaps exist—there's no explicit Kanban task delete, no board create/delete tool despite board_get/list, and no Kanban comments list/delete—but the core workflows are well covered. The eval surface has run/start/status/cancel which is complete.
Average 3.7/5 across 73 of 73 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, destructiveHint=false, openWorldHint=true, but no safety hints about network side effects or auth requirements. The description adds useful behavioral disclosure (it 'writes redacted artifacts' and separates multiple concern dimensions), but doesn't disclose whether this makes external network calls, whether it requires credentials/keys, whether it's expensive or slow, or what 'gated' means operationally. For a test tool that may invoke models, more behavioral context would help.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the core purpose (smoke-test). It's not verbose, but the sentence packs several ideas ('separates endpoint reachability, auth acceptance, model invocation, and assistant answer evidence, writing redacted artifacts') which could be clearer as structured phases. It earns its place but could benefit from slight restructuring.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 params at 0% schema coverage and an output schema present, the description does not explain parameter semantics at all, which is the biggest completeness gap. It also doesn't describe failure modes, exit codes, artifact locations, or how the 'gated' behavior manifests. Given the tool's apparent complexity (multi-phase checks, artifact writing) and zero parameter documentation, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description names zero parameters. The six parameters (home, model, prompt, profile, toolkit_root, timeout_seconds) have no explanation in the description about their purpose or interaction. The agent must infer from bare schema titles like 'Home', 'Toolkit Root', and 'Profile' what values to provide. With 0% schema coverage and zero parameter mention in the description, this is a significant gap that forces the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it's a 'smoke test' of the Hermes API that 'separates endpoint reachability, auth acceptance, model invocation, and assistant answer evidence, writing redacted artifacts.' This gives a reasonably specific verb (smoke-test) and resource (Hermes API) with the distinct sub-checks enumerated. However, it doesn't clearly distinguish itself from sibling tools like hermes_api_health or hermes_api_health_detailed, which could be confused as overlapping health check tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The term 'gated' implies there's some access restriction to using this tool, and 'smoke' implies running a startup verification, giving some implied usage context. But there's no explicit when-to-use, when-not-to-use, or mention of alternatives. It doesn't clarify whether this is for post-deployment verification versus continuous monitoring, nor does it distinguish the smoke test from health checks performed by sibling tools.
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?
Annotations declare readOnlyHint=false, destructiveHint=false (mutating but not destructive), and the description adds meaningful context: it mentions exact-scope patching, multiple safety gates, and side effects of writing a private backup and receipt artifact. However, it doesn't disclose what happens on gate failure (is it a no-op or partial write?), reversibility via the backup, or whether replace_all changes behavior. With annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the patch-apply purpose and lists key behavioral constraints efficiently. It's compact and wastes no words, though it could be split into two sentences for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex, mutating tool with 10 parameters, 6 required, 0% schema coverage, and no description of parameter semantics or failure behavior. Despite having an output schema, the description doesn't cover the prerequisite workflow (e.g., needing a prior proposal or confirmation nonce from a review step), which is critical context for an agent to safely invoke a gated mutation tool. The description covers the gates at a high level but not the parameter-level and workflow-level detail needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for 10 parameters, but it mentions none of them by name except implicitly the gates (allowing the write, sha256, nonce). The description does not explain the semantics of home, profile, toolkit_root, replace_all, config_path resolution, or the old_string/new_string substitution mechanics, which would be essential for an agent to invoke this correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Apply an exact-scope config-file patch') and clearly distinguishes this from sibling hermes_skill_patch_apply by scoping to config files (vs skills). It does not explicitly name the sibling alternative, but the config-vs-skill distinction is clear enough from the action described.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists the gate conditions that must pass but provides no guidance on when to use this tool versus hermes_config_summary, hermes_config_compare_surfaces, or hermes_config_patch_apply alternatives. There is no explicit 'when to use' or 'when not to use' statement, no mention of pairing with a proposal/proposal-review step before applying, and no prerequisites stated.
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?
The description discloses one important behavior: it is 'best-effort' and 'process-local', which conveys that cancellation may not always succeed and is scoped to in-process jobs. However, there are no annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false are all defaults), so the description carries the transparency burden. It does not disclose whether cancellation is reversible, what happens to the job's partial results, or whether re-running is possible afterward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that front-loads the purpose and key caveat ('best-effort', 'process-local'). There is minimal waste, although it could benefit from a sentence about parameter usage or when cancellation might fail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutating operation (cancellation) with an output schema and 4 parameters, 3 of which are undocumented at 0% schema coverage. The description does not explain the return value semantics, what 'best-effort' means operationally (e.g., could it return a failure status?), or the role of the optional parameters. Given the mutation nature and undocumented parameters, the description is not complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description only mentions 'job_id/run_id' parameter. It does not explain the semantics of the optional 'home', 'profile', and 'toolkit_root' parameters, which default to null and appear to configure the toolkit environment. An agent would not know why or when to supply these optional values to resolve a job to cancel.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('cancel') on a specific resource ('process-local Hermes Toolkit MCP async eval job') identified by job_id/run_id. This clearly distinguishes from siblings like hermes_api_jobs_cancel variants and hermes_skill_eval_start. However, the term 'best-effort' is somewhat ambiguous — it doesn't clarify what could prevent the cancellation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for async eval jobs started by the MCP async mechanism, but provides no explicit when-to-use vs alternatives. Siblings like hermes_api_jobs_pause/resume and hermes_job_status exist, but no guidance is given on when to cancel vs pause, or whether this tool only works on the process-local MCP jobs versus the HTTP API jobs. No exclusions or alternatives are mentioned.
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?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, fully covering the safety profile. The description adds 'writing redacted receipts' — a useful side-effect disclosure. But there's no detail on what gets redacted, what receipts are written, or where. With rich annotations providing most transparency, the description adds marginal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with little waste, but the phrase 'Typed GET wrapper' is implementation detail that doesn't serve agent decision-making. It's front-loaded with the core purpose, though it could omit jargon and keep the same informational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There's an output schema present, so return values are documented structurally. With robust annotations and high schema coverage, the description need only cover intent and side-effects, which it does ('writing redacted receipts'). The receipt-writing disclosure addresses a non-obvious behavior. Could mention redaction policy but is largely sufficient for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'resolve' parameter already has a clear description ('Whether the server should return resolved effective values'). The description reiterates 'resolved effective values' but adds no new semantics about the resolve parameter itself. Baseline 3 is appropriate given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'reads kanban orchestration settings and resolved effective values' — a clear verb and resource. However, the term 'Typed GET wrapper' is implementation jargon that adds noise, and there's no explicit differentiation from sibling hermes_kanban_config_get or hermes_kanban_orchestration_update, though the read-only orchestration focus is reasonably clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus hermes_kanban_config_get, hermes_kanban_orchestration_update, or the many other kanban get/modify tools. The 'resolve' parameter behavior is implied but no context about when default resolution is or isn't desired. No exclusion or alternative tools mentioned.
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?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, covering the safety profile. However, the description adds a notable behavioral detail—'writing redacted receipts'—which implies side effects (writes audit logs) that partially contradict the readOnlyHint. This side-effect is disclosed but not contextualized (what are receipts, where do they go?). For a list tool with strong annotations, the burden is low, but the receipt-writing detail deserves more explanation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single compact sentence, front-loaded with the core purpose. The 'Typed GET ... wrapper' implementation detail is minor noise, and 'writing redacted receipts' adds a useful side-effect disclosure. Reasonably efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple (2 optional params, no nested objects, output schema present). The description covers the basic function and the receipt side-effect. However, the ambiguity with hermes_profiles_list and the unexplained 'redacted receipts' mechanism create gaps. Given the schema and annotations richness, this is borderline adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both limit and offset fully documented in the input schema. The description adds nothing about parameter semantics beyond what the schema provides. Baseline 3 is appropriate; description does no harm but also no additional value for params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it lists installed Hermes profiles with descriptions, with a specific verb+resource (lists profiles). However, it does not distinguish from the sibling hermes_profiles_list, which could be confused with this kanban-specific profiles list. The 'Typed GET wrapper' phrasing is implementation detail, not purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives. The sibling hermes_profiles_list exists, suggesting a potential distinction (kanban profiles vs general profiles), but the description offers no differentiation or when-to-use guidance. OpenWorldHint is set but not leveraged.
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 annotations present (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds useful behavioral context about what it does NOT do ('without writing the skill file') and the 'dry/live-gated' and 'bounded' nature. However, it doesn't disclose detail about output/return behavior, error conditions, or side effects of starting an eval job.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that packs several key semantic points (validation step, read boundary, dry/live gating, no file write). It's efficient and front-loaded with the purpose. No wasted words, though the density does trade off some clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 14 parameters, an output schema, and only 2 required fields, with no annotation support (no idempotent/destructive/read-only hints that would help the agent). The description covers the core intent but leaves critical questions unanswered: what does the output contain, how does 'bounded' map to timeout_seconds, what happens with live_eval=true, and how it relates to the other eval-related sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for 14 parameters, but it explains none of them. Terms like 'bounded' and 'dry/live-gated' hint at live_eval and timeout_seconds, but no parameter is explicitly mapped or documented beyond the schema defaults. With 14 params and 0% coverage, this is a substantial gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb sequence: 'Validate a skill id/read boundary, then start a bounded dry/live-gated eval job without writing the skill file.' This clearly identifies the resource (skill eval job) and action (validate + start). However, it doesn't explicitly distinguish from sibling tools like hermes_eval_start, hermes_eval_run, or hermes_api_jobs_create which appear related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it validates a skill id/read boundary and starts a 'bounded dry/live-gated' eval job, which conveys some context about when to use it. However, it provides no explicit when-to-use vs alternatives guidance, no exclusions, and doesn't clarify when this tool should be chosen over the closely-named siblings hermes_eval_start or hermes_eval_run.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the 'writing redacted receipts' side-effect, which is useful beyond annotations. However, it doesn't clarify what 'redacted receipts' means, what response shape it returns (though an output schema exists), or rate-limit/auth considerations. With strong annotations, a 3 is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that efficiently states the core function. No wasted words. It's front-loaded with the action verb and resource. Slightly loses points for the ambiguous 'writing redacted receipts' clause that raises questions without elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has rich annotations (readOnly, idempotent, openWorld, non-destructive) and a 100% schema-covered single parameter, plus an output schema. The description covers the tool's essential function adequately. However, given the large sibling set with closely related health/status tools, a brief note distinguishing it from hermes_api_health_detailed would improve completeness. Still, for a simple read/liveness tool, it's largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there's only 1 parameter with full documentation in the schema ('Whether to perform an HTTP-level connectivity check; always true for this wrapper'). The description adds nothing beyond this since the schema already explains the parameter's semantics including its default and constant behavior. Baseline 3 is warranted since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a 'Typed GET /health wrapper that checks the configured Hermes API server liveness'. Verb+resource is specific ('checks liveness'), though the 'writing redacted receipts' clause adds an unexpected side-effect detail. It's fairly distinguishable from siblings, though hermes_api_health_detailed and hermes_gateway_status are closely related, so some differentiation could strengthen it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description doesn't say when to use this tool vs alternatives like hermes_api_health_detailed or hermes_gateway_status. It mentions 'writes redacted receipts' as a behavioral note, but gives no context about when to prefer this health check over the sibling health_detailed variant or status overview. No exclusions or alternatives are named.
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?
Annotations already indicate readOnlyHint=false (write operation) and idempotentHint=false. The description adds context that this is out-of-schedule triggering and that 'redacted receipts' are written as a side effect, which is useful behavioral disclosure. However, it doesn't disclose rate limits, failure modes, or what happens if the job is already running. With annotations present, the bar is lower, and the description adds a modest amount beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that packs in the endpoint, the verb, the out-of-schedule aspect, and the redacted-receipts side effect. No wasted words. Front-loaded with the key action (triggers a scheduled cron job to run immediately). Could mention one more behavioral aspect, but length is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage, a single documented parameter, an output schema present, and annotations covering the write/non-idempotent nature, the description needs to add only the out-of-schedule triggering semantics and the redacted-receipts side effect, which it does. This is reasonably complete for a simple trigger action. Slightly more usage context would push it higher, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with a single parameter 'job_id' described as 'Unique job identifier.' The description's mention of 'writing redacted receipts' is a side effect, not a parameter. The description doesn't add parameter detail, but with only one fully-documented parameter, the schema carries the load appropriately. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('triggers a scheduled Hermes cron job to run immediately, out of schedule') with the endpoint path (POST /api/jobs/{job_id}/run). It's clear about what the tool does. It doesn't explicitly distinguish from siblings like hermes_job_status, hermes_job_cancel, hermes_api_jobs_pause/resume, but the verb 'run' plus 'out of schedule' does separate it reasonably from other job-management tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions this is for running a job 'out of schedule' and triggering it immediately, which implies usage context ('when you want to trigger now rather than wait for schedule'). However, it provides no explicit when-not-to-use guidance, no alternatives, and no note about prerequisites (e.g., whether the job must exist or be paused). For a job-management tool with many siblings (pause, resume, cancel, status, create, update), guidance on when to use this over alternatives is notably absent.
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?
Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true. The description adds 'writing redacted receipts,' which is useful behavioral context not in annotations. However, it doesn't mention idempotency behavior (though the schema describes the idempotency_key param), authentication requirements, or side effects like worker dispatch. The 'redacted receipts' mention is a genuine addition but sparse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core action and enumerates the key parameters compactly. It's not padded with fluff or redundant claims. Minor deduction for not being fully self-contained (relies on reader parsing the parameter list correctly).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 100% parameter coverage, the description's job is largely about orientation. For a 13-parameter creation tool, it adequately overviews the input surface. The missing usage guidance and sparse behavioral disclosure slightly reduce completeness, but the rich schema and output schema compensate substantially.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 13 parameters. The description lists the key fields (title, body, assignee, priority, parents, triage flag, idempotency key, workspace options) but adds no semantic detail beyond what the schema provides. This is the baseline 3 since the schema carries the full load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a 'Typed POST /api/plugins/kanban/tasks wrapper that creates a Kanban task' with a specific verb (creates) and resource (Kanban task), and lists a comprehensive set of fields it handles. It distinguishes from siblings like hermes_kanban_task_update by indicating creation. However, it doesn't explicitly contrast with sibling creation tools (liked hermes_kanban_link_create), so it's slightly below a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like hermes_kanban_task_update or hermes_kanban_task_specify. It doesn't mention prerequisites (e.g., what's needed to create a task), whether this is the primary entry point for task creation, or when a sibling might be more appropriate. The write action is implied but no contextual direction is given.
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?
Annotations declare readOnlyHint=false and destructiveHint=false, conveying it's a mutation that isn't destructive. The description adds the 'writing redacted receipts' behavior, which is genuinely useful side-effect disclosure. However, it doesn't disclose auth requirements, rate limits, or whether the comment appends asynchronously. With annotations already covering the safety profile, the added 'redacted receipts' note earns a mid-range score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that conveys the HTTP method, resource path, function, and parameters. It's not verbose or wasteful. Minor deduction for the jargon-heavy 'Typed POST wrapper' opener, which adds little for an agent reader, but overall it's efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (so return values needn't be described) and full schema coverage. The description adequately conveys the core operation and the redacted-receipts side effect. However, given the presence of many sibling kanban tools and a board parameter that affects task lookup semantics, a bit more context about when board is needed vs the default would strengthen completeness. Adequate but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters (id, body, board) with descriptions. The description adds the 'comment text and optional board query param' mapping, plus the 'redacted receipts' context. Since the schema fully covers parameter meanings, this exceeds the baseline 3 by clarifying which parameter maps to the comment vs the board query param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool appends a comment to a Kanban task via POST, and mentions the JSON body and optional board parameter. While 'Typed POST wrapper' is a bit jargon-heavy, the core purpose (create a task comment) is unmistakable and distinct from sibling tools like hermes_kanban_task_update or hermes_kanban_link_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool vs alternatives, mention any prerequisites (e.g., needing task_to_read first), or explain when a comment should be created vs using other kanban tools. The openWorldHint=true is set but the description provides no guidance on context or invocation circumstances.
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?
Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false — describing a write operation without annotations contradiction. The description adds 'writing redacted receipts' which gives partial context about side effects. However, it does not explain persistence behavior, whether the created job persists across restarts, authentication/permission requirements, or how receipt redaction is significant. With some annotation coverage, a 3 is appropriate but the description could be richer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, compact sentence that front-loads the core action ('Typed POST /api/jobs wrapper that creates a scheduled Hermes cron job') and then enumerates the configurable fields. It's efficient with no filler. Slight deduction for cramming 'writing redacted receipts' at the end, which is behavioral context that might deserve more prominence, but overall very lean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to explain return values. The core create semantics, field list, and a side effect are covered. However, the description omits practical details that would help an agent invoke correctly: schedule format expectations, whether prompt/schedule have format restrictions, and the relationship to the run/pause/resume job lifecycle tools. It's adequate but not rich for a creation tool in a large tool family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 6 parameters already has a schema description (e.g., 'Optional model override', 'Prompt the cron job will run', 'Cron schedule expression or interval string'). The description groups them as 'skills, provider/model overrides, and delivery target' but adds no syntax, format, or interaction details beyond what the schema already documents. Baseline 3 is correct given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Typed POST /api/jobs wrapper that creates a scheduled Hermes cron job' — clear verb (creates) + resource (scheduled Hermes cron job). It lists the configuring fields (prompt, schedule, skills, provider/model overrides, delivery target) and the side effect (writing redacted receipts). It doesn't explicitly differentiate from the sibling jobs tools (list/get/update/delete/pause/resume/run), but 'creates' clearly implies a create operation distinct from the rest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does and what fields it accepts, so an agent knows to use it when creating a new cron job. However, there is no explicit when-to-use guidance, no exclusions, and no mention of related alternatives (e.g., hermes_job_status, hermes_api_jobs_run) or constraints like whether schedule requires a specific cron format. Usage context is implied by the create semantics but not explicitly documented.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds the 'writing redacted receipts' behavior, which is a useful side-effect disclosure beyond what annotations state. However, it doesn't explain pagination behavior, response structure, or implications of fetching from a remote API server.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that covers the core purpose, source, and key parameters efficiently. The mention of 'redacted receipts' is a meaningful addition. It's front-loaded with the key verb and resource. Slightly dense but acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema present, so return values are structurally documented. The tool is a simple read-only list operation with well-documented params and safety annotations. However, given the large number of closely-related job tools in the sibling list (jobs_get, jobs_create, jobs_pause, jobs_resume, jobs_run), a bit more differentiation would improve completeness, though the simple nature of this tool keeps it adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (limit, offset, status) are well-documented in the schema. The description mentions limit, offset, and status filter, but adds no additional semantic detail beyond what the schema already provides. The baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a typed GET /api/jobs wrapper listing scheduled Hermes cron jobs with optional limit, offset, and status filters. It specifies the verb (list), resource (scheduled Hermes cron jobs), and source (configured Hermes API server). It doesn't explicitly distinguish from sibling hermes_api_jobs_get, but the 'list' vs 'get' distinction is implied by the name and multiple-item listing semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it lists jobs from the configured API server, which provides some context. However, it doesn't explicitly contrast with sibling tools like hermes_api_jobs_get (single job fetch), hermes_job_status, or hermes_api_jobs_run. No when-to-use or when-not-to-use guidance is given relative to the many closely-related job tools in the sibling list.
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?
Annotations provide only readOnlyHint=false (a mutation), leaving the description to carry behavioral disclosure. It adds that the job is 'not deleted' and mentions 'writing redacted receipts,' which is useful behavioral context about side effects. However, it doesn't address idempotency concerns (pausing an already-paused job), return semantics, or whether the write requires specific permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence conveys the purpose, the HTTP wrapper nature, the behavior (suspend + not delete), and a side effect (redacted receipts). Efficient and front-loaded with the key verb and resource. Minor deduction for cramming the 'redacted receipts' detail without context on why that matters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward pause operation with one well-documented parameter and an output schema present. The description covers the essential semantics. However, with no annotations for possible side-effect or idempotency warning, and given sibling tools for resume/delete/cancel exist, a bit more guidance on relationship to those tools would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the single parameter job_id is documented as 'Unique job identifier.' The description adds the detail that the endpoint is POST /api/jobs/{job_id}/pause, which clarifies job_id lives in the URL path. But there's no additional format or semantics beyond the schema baseline, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a 'Typed POST /api/jobs/{job_id}/pause wrapper' that 'suspends a scheduled Hermes cron job without deleting it,' giving a specific verb+resource+action. It distinguishes from resuming/deleting jobs present in the sibling set. However, it doesn't explicitly name an alternative tool like the high-scoring example does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives contextual clues about what the tool does (pause vs delete) which implies usage for suspending rather than removing jobs. However, it doesn't explicitly state when to use this vs hermes_api_jobs_resume, hermes_api_jobs_delete, or hermes_job_cancel, leaving the agent to infer from naming alone.
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?
The description mentions 'writing redacted receipts' as a side effect, which adds genuine value beyond the annotations. However, annotations already flag readOnlyHint=false and idempotentHint=false, and the description doesn't disclose what 'redacted receipts' writes or where, nor reconcile the read intent with readOnlyHint=false. With annotations present, the description adds some context but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that packs in the method (GET), resource, purpose, side effect, and access gates without waste. It's front-loaded with the primary purpose and efficient in expression.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to explain return values. The description covers the purpose and gating requirements. However, the 'writing redacted receipts' side effect is left unexplained (what/where), and for a tool where readOnlyHint=false, the behavioral details are sparse. Adequately complete but with gaps around the side-effect behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter (run_id) is 100%, so the schema already fully documents it. The description adds no parameter-specific semantics beyond what the schema provides, meeting the baseline of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a typed GET wrapper that reads a Hermes run status. It identifies the resource (Hermes run by ID) and the verb (reads status). It distinguishes somewhat from siblings like hermes_api_runs_start/stop/events, though it doesn't explicitly differentiate from sibling read tools like hermes_kanban_run_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is given. The auth/gate requirements ('api_call tier with live and external-side-effect gates') hint at preconditions, but there's no guidance distinguishing this from other run-related tools or alternatives. Sibling tools like hermes_api_runs_events and hermes_kanban_run_get exist but aren't referenced.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds value with 'redaction and presence-only handling for sensitive values,' which is useful behavioral disclosure about how sensitive config values are treated during comparison. However, it doesn't explain what 'presence-only handling' means concretely or describe the comparison output format for differing values. Given strong annotation coverage, a 3 is appropriate — the description adds meaningful context but isn't rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that packs purpose and key behavioral traits (redaction, presence-only, allowlisted, top-level keys) efficiently. There is no wasted wording and no filler. It could arguably add a sentence about usage or output, but as written it earns its place without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters with 0% schema coverage and 2 required, plus an output schema (though the return shape isn't described). The description names the comparison function and sensitive-value handling but does not clarify the purpose of the optional params (home, profile, toolkit_root), the meaning of 'allowlisted' in operational terms, or the comparison output structure. For a tool of this complexity with zero schema coverage, the description is functional but leaves material gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description mentions 'selected top-level config keys' and 'two allowlisted YAML surfaces,' which maps to the 'keys' and the two config params (left_config/right_config). However, the meaning of 'allowlisted' in relation to the config surfaces, and the roles of home, profile, and toolkit_root (likely path resolution params), are undocumented in both schema and description. The description covers the core comparison params but leaves the supporting params unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation: 'Compare selected top-level config keys across two allowlisted YAML surfaces.' It names the resources (config keys, YAML surfaces) and the verb (compare). It could be slightly clearer about the output being a diff/report, but it distinguishes this from hermes_config_summary (which summarizes a single config) and differentiates from patch tools. The phrase 'allowlisted' adds scoping context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies comparative usage between two config surfaces, and sibling tools like hermes_config_summary, hermes_config_patch_apply, and hermes_profiles_list provide natural alternatives. However, the description does not explicitly state when to use this tool vs alternatives, nor does it mention prerequisites like whether the configs must be loaded or whether keys is optional. The 'selected top-level config keys' wording implies keys parameter drives comparison, but no explicit when/when-not guidance is given.
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?
Annotations declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true — so the safety profile (destructive mutation, side effects) is already communicated. The description reinforces this by saying 'only at owner policy tier' and listing gates, which signals this is a high-risk, heavily-guarded operation. It adds the notion of prerequisite verification (verified artifact, hashes) beyond annotations. However, it doesn't disclose what exactly gets destroyed/modified, whether the command executes arbitrary shell, or what happens on gate failure. With annotations already marking destructive=true, the description adds moderate but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that packs too much jargon into one clause. It front-loads the core action ('Run a preconfigured deploy repair command against a verified repair-plan artifact') which is good, but then appends a long gate list that reads as run-on. Splitting into a clear purpose sentence plus a short 'requires X, Y, Z gates' sentence would improve readability. Each gate name is earned but the presentation is cramped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a destructive, complex tool (destructiveHint=true, 9 params, multiple hash/nonce gates) but has an output schema which removes the need to describe return values. The description covers the gating mechanism and owner-tier requirement. However, with 0% schema description coverage and high complexity, it falls short: it doesn't explain the significance of home/profile/toolkit_root, what constitutes a valid 'verified repair-plan artifact', or the workflow prerequisite (e.g., must run hermes_deploy_repair_plan first to obtain the hashes). For a dangerous tool that requires a verification workflow, this is a meaningful completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description references the key safety parameters: 'command-hash, plan-hash, and confirmation nonce gates' which map to expected_deploy_repair_command_sha256, expected_repair_plan_sha256, and confirmation_nonce. This tells the agent these params serve as integrity-verification gates. The phrase 'proposal_artifact_dir' is partially explained by 'repair-plan artifact'. However, with 9 parameters and 0% schema coverage, the description names only the hash/nonce params and leaves home, profile, toolkit_root, timeout_seconds unexplained — a gap for a multi-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Run a preconfigured deploy repair command against a verified repair-plan artifact' — a specific verb ('Run'), resource (deploy repair), and clear target (verified repair-plan artifact). It distinguishes from sibling hermes_deploy_repair_plan (planning vs applying) and clarifies this is the apply side. However, the cascade of gate terminology ('at owner policy tier with git/config/gateway/external gates, command-hash, plan-hash, and confirmation nonce gates') is dense jargon that obscures the core action for an agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning 'verified repair-plan artifact' and 'only at owner policy tier', suggesting it should only be invoked after a verified repair plan exists and at high privilege. It names gates (git/config/gateway/external) that serve as preconditions. However, there's no explicit 'when to use vs alternatives' — no mention of not using it when no verified plan exists, nor clear contrast with hermes_deploy_repair_plan. The gating hints are implicit rather than explicit.
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?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds that it 'nudges' the dispatcher to skip the wait and writes 'redacted receipts', which provides some operational context. However, with no annotations covering write behavior (no auth requirements, no rate limits, no side-effect details beyond skipping the wait), the description carries a moderate burden but doesn't fully disclose what 'nudge' implies operationally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single dense sentence that packs the endpoint, verb, purpose, params, and behavior efficiently. It's front-loaded with the core action. Slightly overloaded but still readable; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, all 4 params documented at 100% coverage, and the description covers the main action (skip 60s wait). For a dispatch-triggering tool, the description is reasonably complete. However, it doesn't clarify side effects of nudging beyond skipping the wait, what 'redacted receipts' means for the caller, or whether repeated nudges are safe (idempotentHint=false hints otherwise but the description doesn't elaborate). Given the operation involves triggering work, slightly richer context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description lists max, dry_run, board, and tenant query params, which mirrors the schema. It doesn't add any semantic meaning beyond the schema—e.g., what 'max' bounds in relation to the endpoint's behavior, or how dry_run relates to 'redacted receipts'. The description adds no value over the well-documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a typed POST /api/plugins/kanban/dispatch wrapper that nudges the kanban dispatcher to skip the 60s wait, with optional query params and redacted receipts. It names the verb (nudge), resource (kanban dispatcher via POST dispatch endpoint), and key behavioral effect (skip wait). It differentiates from siblings by virtue of the POST dispatch action, though it doesn't explicitly name a sibling for exclusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a nudge to trigger immediate dispatch rather than waiting 60s, and mentions dry_run for testing. However, it doesn't explicitly say when to use this vs alternatives (e.g., when to use hermes_kanban_task_update or hermes_kanban_tasks_bulk_update instead), nor does it state any prerequisites or conditions that make nudging appropriate or inappropriate.
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?
Annotations already declare readOnlyHint=false and idempotentHint=false, so the write semantics are covered. The description adds that it writes to config.yaml and produces 'redacted receipts', which is useful behavioral context. However, it doesn't explain what 'redacted receipts' look like, what happens to concurrent updates, or whether this requires restart to take effect. The description adds moderate value beyond annotations but doesn't fully disclose mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that names the endpoint, the fields affected, and where they're written. No wasted words. Slightly below 5 because it could use a second sentence to clarify behavioral expectations, but as written it's tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists which helps with return value expectation. However, this is a mutating operation with 3 optional fields, and the description doesn't clarify whether updating one field leaves others unchanged, whether all three must be provided together, or what side effects occur on the running system (does it require restart like hermes_gateway_restart hints?). Given the complexity of an orchestrator-update operation, slightly richer context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter having a clear description (e.g., 'Whether to automatically decompose triaged tasks', 'Default assignee for newly created tasks'). The description adds marginal value by listing all three updatable fields but doesn't provide anything beyond what the schema documents. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it is a 'Typed PUT /api/plugins/kanban/orchestration wrapper that updates orchestrator_profile, default_assignee, or auto_decompose in config.yaml'. This clearly identifies the verb (update), resource (kanban orchestration settings), and the specific fields affected. It distinguishes from sibling tools like hermes_kanban_orchestration_get. It's slightly less than a 5 because it's phrased as a 'wrapper' which adds implementation detail rather than pure function clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates the use case via the field names and 'config.yaml' mention, but there is no explicit guidance on when to use this vs the put/get variants, or any security/permission context. It's clear that this updates orchestration settings, but no alternatives or exclusions are named. For a mutation tool with no required params, guidance on consequences would be valuable.
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?
Annotations provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the mutation profile is declared structurally. The description adds one meaningful behavioral detail: it writes 'redacted receipts,' which is useful peripheral-context. However, it doesn't elaborate on what 'redacted receipts' means or what side effects accompany the update, leaving some ambiguity. Without annotating the receipt behavior, the description partially compensates but could go further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that efficiently conveys the verb, resource, effect, and a side-effect (redacted receipts). It's appropriately compact with no wasted words. Slightly more detail on receipts could push it higher, but it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and coverage is high, so much is structurally specified. The 'redacted receipts' detail hints at an important behavior not otherwise disclosed. However, for a mutation wrapper, it doesn't describe auth requirements, potential outcomes, or error conditions. It's adequate given the strong schema but not rich enough to be considered complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters (name, description). The description adds minimal param-level meaning beyond restating 'sets or clears a user-authored description' and mentioning redacted receipts. With full schema coverage, baseline 3 is appropriate since the description doesn't materially enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource structure ('Typed PATCH /api/plugins/kanban/profiles/{name} wrapper') clearly stating it sets or clears a profile's description. It distinguishes the 'update/set/clear' action on profile description from siblings like hermes_kanban_profiles_list or hermes_kanban_link_create, though it could more explicitly differentiate from the many other update tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is a PATCH wrapper and mentions setting or clearing description, which implies when to use it. However, it doesn't state explicit exclusions or mention alternatives (e.g., when to use a different profile-related tool). The implied context is clear enough for selecting this over list/get tools but lacks explicit when-not guidance.
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?
The description discloses that it writes a 'private backup and receipt artifact,' which is useful behavioral context. The four-gate check and 'exact-scope' constraint add transparency about safety behavior. However, destructiveHint=false is already in annotations and the description doesn't contradict it; the description adds moderate value but doesn't detail failure behaviors (what happens when a gate fails, whether partial writes occur). With annotations present but sparse (all hints false/neutral), the description partially compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that packs in the gating condition, the artifact behaviors, and the exact-scope constraint with zero wasted words. Very efficient for a complex mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a high-complexity mutation tool with 12 parameters, no schema description coverage, and an output schema the description doesn't characterize. The description mentions backup and receipt artifacts but doesn't describe the return result, failure semantics when gates fail, or the relationship to the proposal tool flow. Given the rich gating and error-handling complexity, the description is substantially under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description carries full burden for the 12 parameters, but it names only some: allow_skill_write gate (implicitly tied to skill_id and expected_original_sha256), confirmation_nonce, old_string/new_string. Parameters like home, source, profile, replace_all, file_path, toolkit_root are completely undocumented. The description adds some semantics by explaining the gating relation but leaves major parameters unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('apply'), the resource ('exact-scope skill-file patch'), and the gating mechanism (mutation policy, allow_skill_write, expected sha256, confirmation nonce). It distinguishes this write-apply tool from sibling hermes_skill_patch_proposal and hermes_config_patch_apply. However, it doesn't explicitly differentiate against all patch-related siblings, slightly limiting sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for applying skill patches, and the gating conditions (all four gates must pass) provide context on when invocation is appropriate. However, it doesn't explicitly state when NOT to use this tool versus hermes_skill_patch_proposal (proposal vs apply distinction is only implicit) or hermes_config_patch_apply (skill vs config distinction implied).
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is well covered by annotations. The description adds the 'writing redacted receipts' behavior, which is useful context. The schema reveals that the capability filter parameter is effectively ignored ('returns all capabilities regardless'), which is useful behavioral context. No contradictions with 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core action and resource. The mention of 'writing redacted receipts' adds behavioral context without excessive verbosity. Efficient and reasonably complete for what it communicates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only capabilities query with a single optional parameter, full schema coverage, complete annotations, and an output schema present, the description is reasonably complete. It doesn't need to document return values since an output schema exists. Minor gap: doesn't clarify the purpose/value of the tool versus related status/health/skills query tools given the large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single optional parameter that has detailed enum values and a description noting the parameter is effectively ignored. The description adds no additional parameter meaning beyond what the schema provides. Baseline 3 is appropriate since the schema fully documents the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Typed GET /v1/capabilities wrapper that returns the configured Hermes API server capability surface'. It has a specific verb (GET/returns) and resource (capability surface). However, it doesn't distinguish itself from siblings like hermes_status_overview or hermes_api_health, which could overlap in purpose. The 'writing redacted receipts' behavior is a useful differentiator but unclear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it's for fetching the server capability surface but provides no explicit guidance about when to choose this vs alternatives like hermes_api_health, hermes_api_skills_list, or hermes_api_toolsets_list which overlap in capability spaces. The parameter's default behavior (returns all regardless) is documented in the schema, not the description. No when-not-to-use guidance is present.
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?
Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering the safety profile well. The description adds useful context beyond annotations: it mentions 'writing redacted receipts' as a side effect, which is behavioral information the annotations don't convey, and it clarifies this is a network call to the configured Hermes server. With strong annotations, this is solid supplemental disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the endpoint and verb, and includes a meaningful side-effect disclosure ('writing redacted receipts') without bloat. Compact and effective, though the phrasing 'Typed GET...wrapper' is a bit jargon-heavy and could be clearer for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter GET with strong annotations (readOnly, idempotent, non-destructive), an output schema present, and 100% parameter coverage, the description is reasonably complete. It addresses the retrieval purpose and the redacted-receipt side effect. It could note whether receipts are a logging artifact or a returned artifact, and how redaction works, but for a read operation this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the response_id parameter fully documented ('Stored response id to retrieve') including pattern, min/max length constraints. The description itself doesn't add parameter details beyond what the schema provides, but given full schema coverage, the baseline of 3 is appropriate. The description's mention of the underlying endpoint URL implicitly clarifies the parameter maps to the path segment {id}.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (retrieves), resource (stored response from Hermes API server), and the underlying endpoint (GET /v1/responses/{id}). It specifies it's a 'Typed wrapper' indicating a structured abstraction. It's slightly distinct from siblings like hermes_api_runs_get or hermes_api_docs_read since it targets the /responses resource specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it retrieves a stored response but does not state when to use this versus alternatives like hermes_api_runs_get, hermes_api_jobs_get, or hermes_api_chat_completions. No scenario guidance, no exclusions, no note on how a response_id is obtained (presumably from hermes_api_responses_create). The 'writing redacted receipts' side effect is mentioned but not explained in terms of 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?
Annotations exist but are minimal: readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. These already signal a non-read, non-idempotent mutation with external side effects. The description adds the behavior of 'writing redacted receipts' and the gate/permission requirements, which is useful context beyond the annotations. However, it doesn't disclose what happens to the run's state, whether the stop is reversible, or failure/consistency behavior. With annotations carrying a portion of the burden, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence that front-loads the mechanism (typed POST wrapper), the action (requests stop), the side effect (redacted receipts), and the gates. Slightly verbose with the gate enumeration, but each clause earns its place. No filler or redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists (though not shown), annotations are present, schema covers 100% of params, and the descriptions is compact but competent. The tool is a straightforward wrapper for a known endpoint. It covers permissions/gates and side effects. Minor gap: doesn't describe what the response/return looks like or what happens on failure, but with an output schema present this isn't the description's job. Complete enough for a well-typed wrapper tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — all three parameters (run_id, reason, wait_seconds) have descriptions in the schema. The description itself adds the 'redacted receipts' write behavior and gate requirements but does not add parameter-level detail beyond the schema. Per the baseline rule (coverage >80%), a 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies it as a typed POST wrapper for /v1/runs/{run_id}/stop that requests a Hermes run stop, writing redacted receipts. It distinguishes itself from siblings like hermes_api_runs_start (start flow) and hermes_api_runs_get/events (read flows). However, it doesn't explicitly contrast against job_stop-like siblings since none exist; hermes_api_jobs_pause/cancel are nearby but different resources. Clear verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tier requirement (api_call) and gate requirements (live, agent-tool, external-side-effect), giving conditional context for when the tool is permissible. It also implies use for stopping runs, but does not explicitly say when NOT to use it or name alternatives (e.g., when to prefer graceful stop vs hard cancel, or relation to hermes_job_cancel). Adequate but no explicit exclusions or alternatives.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'without starting, stopping, restarting, or mutating services' clarification, which reinforces safety but doesn't describe return format or what 'status' includes beyond pid/lock/log path state. The description aligns with (and slightly extends) the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, compact sentence that is front-loaded with the action and scope, and efficiently clarifies the non-mutating nature. Minimal waste; clear and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only inspection tool with 0 required parameters and an output schema available. The description covers the core purpose and safety profile adequately. The main gap is the undefined parameter semantics (home/profile/toolkit_root), but given the tool's simplicity and output schema presence, the overall burden is modestly met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden for the 3 optional parameters (home, profile, toolkit_root). However, the description does not explain what these parameters mean or how they affect the gateway path lookup. It adds no parameter-level semantics beyond what the schema types provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspect') with a clear resource ('gateway pid/lock/log path state') and explicitly states what it does NOT do (starting, stopping, restarting, mutating services). It distinguishes reasonably from siblings like hermes_gateway_restart and hermes_status_overview, though it could name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys a read-only inspection use case and implicitly contrasts with mutation tools (restart, start/stop), but does not explicitly name alternatives or state when to prefer this over hermes_status_overview or hermes_api_health which appear to overlap in the read/inspection space.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that it 'writes redacted receipts' which is a genuine behavioral trait beyond the annotations, but doesn't elaborate on what those receipts are for or whether they have side effects. The description adds some context (redaction behavior) beyond the annotations, but doesn't explain return format or pagination semantics in depth. With annotations covering the read-only/idempotent profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently enumerates the tool's function and all params without redundancy. It's concise and front-loaded with the primary action ('reads a Kanban board'). Minor deduction because 'writes redacted receipts' is a somewhat cryptic clause that could be more explanatory.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output_schema present, the description doesn't need to explain return values. Annotations are rich (readOnly, idempotent, openWorld, non-destructive), covering the safety profile. The 100% schema coverage handles parameter documentation. The only gap is lack of guidance about pagination defaults or default board behavior, but given the overall rich structured metadata, the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (board, limit, offset, tenant, include_archived) already has a description in the schema. The tool description adds minimal value beyond this—it just restates the parameter names without adding semantics about how they interact (e.g., what the default board is, how archived filtering combines with pagination). With full schema coverage, the baseline of 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it's a 'Typed GET /api/plugins/kanban/board wrapper that reads a Kanban board' with clear verb+resource (reads a board). It lists the key filtering capabilities (board slug, tenant, archived filter, limit, offset). However, it doesn't differentiate from siblings like hermes_kanban_boards_list (which lists boards vs. reads one board's tasks), though the tool name itself does differentiate reasonably. It's clear but doesn't explicitly contrast with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it reads a board with optional filters, implying when to use it (to read board contents). However, there's no explicit when-not-to-use guidance or mention of alternatives like hermes_kanban_task_get for single task reads or hermes_kanban_boards_list for enumerating boards. The availability of filter parameters implies scenification but exclusions aren't stated.
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?
Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, which already establish this as a mutating, non-idempotent operation. The description adds 'writing redacted receipts' as a behavioral trait, which is genuinely useful context about what side effects occur. No contradiction with annotations. However, it does not disclose auth requirements, failure modes, or what happens on invalid parent/child IDs. With annotations present, the base burden is lower and the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that packs in the HTTP method, endpoint, purpose, relationship direction, body format, optional board param, and side effect (redacted receipts). It is dense but efficient with no wasted words. Could arguably be split for readability, but for a tool description it's appropriately brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that schema coverage is 100%, an output schema exists, required params are clearly defined, and annotations cover the mutation/idempotency profile, the description fills the key gaps: relationship direction semantics and the receipt-writing side effect. For a relatively simple link-creation tool, this is reasonably complete. The main missing element is clarity on what happens when a link already exists or on dependencies validation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (parent_id, child_id, board) with descriptions like 'Child task id such as t_xxxxxxxx.' The description adds the notational meaning of the relationship (parent_id -> child_id as a dependency direction) and notes the board param is optional, but these are marginal additions over the already-complete schema coverage. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a typed POST wrapper that adds a dependency relationship (parent_id -> child_id), which is specific and distinguishes it from sibling kanban tools like kanban_task_create or kanban_link_delete. However, the phrase 'typed POST wrapper' is somewhat jargon-heavy and the core action of creating a dependency link could be stated more plainly. The directionality notation (parent_id -> child_id) adds useful specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when this tool is used (to add kanban task dependencies) but does not explicitly state when to use it vs alternatives like kanban_task_create or kanban_link_delete. No explicit comparison to siblings or when-not-to-use guidance is given. The board param default is mentioned in the schema, and the description notes it's optional, which is helpful contextual information.
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?
Annotations provide readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds that it's a DELETE wrapper and mentions 'writing redacted receipts' as an output behavior. However, it doesn't clarify whether the operation is destructive to task data (only the link is removed) or what happens to orphaned links. With annotations present, the bar is lower, but the 'redacted receipts' phrasing is vague and could be clearer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single compact sentence that conveys the HTTP verb, endpoint, parameters, and output behavior. No redundancy, front-loaded with the core action. The sentence is slightly dense with the 'typed wrapper' and 'redacted receipts' jargon, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has an output schema, so return value documentation isn't needed in the description. With 2 required params plus optional board, and good schema coverage plus annotations, the description sufficiently covers the mechanism. The main gap is what 'redacted receipts' means and whether removing a dependency has cascade effects, but the sibling count and general DELETE semantics keep this reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (board, child_id, parent_id) having descriptions in the schema. The description adds context about parent_id/child_id being query params and board being optional, but it doesn't add meaningful meaning beyond the schema's descriptions. Baseline 3 is appropriate when schema covers everything. The 'such as t_xxxxxxxx' format hints add some value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a typed DELETE wrapper that removes a dependency identified by parent_id and child_id query params, with an optional board param. Verb+resource+identification method are clear. However, it doesn't distinguish from sibling hermes_kanban_link_create, though the DELETE verb and parent/child removal semantics make the purpose fairly self-evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to use when removing a Kanban task dependency/link, but it doesn't explicitly state when to use vs. alternatives like hermes_kanban_link_create. There's no statement about 'when not to use' or prerequisites. The board defaults to configured default board, which gives some context. Adequate but with no explicit exclusions or alternatives mentioned.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is well-covered. The description adds the behavioral detail that it 'writes redacted receipts,' a noteworthy side effect beyond the read operation the annotations suggest. However, it doesn't explain auth requirements, rate limits, or error/not-found behavior for a non-existent run_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence. It front-loads the HTTP verb, resource path, and return contents. Some wording is slightly jargon-heavy ('Typed GET ... wrapper'), but there is zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it has a full output schema, a single well-documented parameter, and strong annotations covering safety/idempotency, the description is largely complete. The main gap is clarity around how this differs from the similarly-scoped hermes_kanban_run_inspect sibling, though that is a usage-guidelines concern more than completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the run_id is fully described with an example format '741 or run_xxxxxxxx'). The description reinforces that run_id refers to a single run and adds that the read returns single-run detail. This matches the baseline 3 for full schema coverage; the description adds minimal supplemental semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (GET), resource (kanban runs single-run detail), and specific fields returned (task id, status, timestamps, exit code, log path). It stands distinct from siblings like hermes_kanban_run_inspect and hermes_kanban_task_get. However, it doesn't explicitly distinguish from the closely-named hermes_kanban_run_inspect sibling, which may be a near-overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a read-only single-run retrieval tool but offers no explicit when-to-use guidance or exclusions versus hermes_kanban_run_inspect or hermes_api_runs_get. The schema's title and the GET wrapper wording give context, but no explicit alternatives or conditions are mentioned.
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?
Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutation that's not destructive. The description adds useful context: 'writing redacted receipts' and the status restriction on 'running' (set by dispatcher). However, it doesn't disclose side effects like whether unassigning via empty string affects claim state, or how the completion path interacts with complete_task beyond forwarding. The 'redacted receipts' detail is a genuine addition but could go further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, reasonably dense sentence that front-loads the verb, resource, fields, and one behavioral trait (redacted receipts). No wasted words. It could arguably be more compact but is efficient and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there's an output schema, the description need not explain return values. The tool is a straightforward mutation with 1 required param, clear annotations, and rich schema descriptions. The main gap is not explaining field interdependencies (like whether completion paths for 'done' status require summary/result/metadata), but annotations and schema coverage carry most of the burden. Adequate for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each of the 11 parameters well (id format, status enum, board slug pattern, assignee empty-string semantics). The description adds minimal beyond the schema - it lists which fields can be updated but doesn't clarify interaction semantics (e.g., does setting status to 'done' require result, does 'blocked' require block_reason). Since coverage is high, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a 'Typed PATCH wrapper that updates status, assignee, priority, title, body, result, or completion summary for one Kanban task.' This is specific verb+resource+fields and distinguishes it from sibling tools like hermes_kanban_task_create, task_specify, and task_decompose. It could slightly improve by noting it differs from bulk_update, but it does convey the single-task scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'writing redacted receipts' which gives some sense of what happens, and the status schema notes 'running is not allowed because status is set by the dispatcher/claim path.' However, there's no explicit when-to-use vs when-not-to-use guidance (e.g., when to choose bulk_update vs this, or when completion summary should be used). The 'completing a task' hint in result and the summary-to-complete_task reference imply some flow, but no exclusions or alternative tool references are given.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the valuable scoping constraint that contents are NOT exposed (only 'surface presence'), which is genuinely useful behavioral context beyond what annotations provide. However, it doesn't describe output shape, pagination, or failure behavior — though the output schema partially compensates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, well-crafted sentence that front-loads the purpose and adds a meaningful scope qualifier (negative scope). Zero wasted words. It earns its length by communicating both the positive action and the explicit boundary of what it does not touch.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, strong annotations (read-only, idempotent, non-destructive), 100% schema parameter coverage, and zero required parameters — a relatively simple list operation. The description handles the key ambiguity (what's excluded vs included) with the negative scope statement. Parenthetical package of annotations + output schema + description feels sufficient for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all three parameters (home, profile, toolkit_root) documented in the schema. The description adds minimal parameter-level nuance beyond the schema. The 'Must resolve under configured allowed roots' constraints are already in the schema descriptions, so the description adds little beyond what's structured. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists local Hermes profiles and profile-local surface presence, with a specific negative scope ('without exposing memory, skill, plugin, or config contents'). It distinguishes intent well among the many hermes_* siblings by emphasizing the 'surface presence' focus. Could be slightly more specific about what 'surface presence' means, but the verb+resource+scope is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the tool is for list/inspection purposes but doesn't explicitly state when to use it versus alternatives like hermes_config_summary, hermes_skills_list, or hermes_status_overview. The negative scope ('without exposing memory/skill/plugin/config contents') implicitly guides toward choosing this over content-rich siblings, but no sibling is named and no explicit exclusions are stated.
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?
Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds the 'writing redacted receipts' side effect note, which is useful beyond the annotations. However, it doesn't disclose failure modes, permission requirements, or state-change specifics beyond 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single compact sentence that front-loads the action and includes the endpoint details and side-effect note. No wasted words, though 'Typed POST ... wrapper' boilerplate is somewhat verbose and could be considered unnecessary for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter internal API wrapper with a simple action (resume), the description is reasonably complete. It has an output schema, full param coverage, and adequate annotations. It could benefit from noting prerequisites (e.g., job must exist and be paused), but overall it's sufficient for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single required parameter (job_id) is well documented as 'Unique job identifier' in the schema. The description's mention of the POST endpoint path (/api/jobs/{job_id}/resume) reinforces how job_id binds to the URL, adding mild value. With full schema coverage, baseline is 3, and the description adds a small increment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb (resume), resource (previously paused scheduled Hermes cron job), and mentions the side effect of writing redacted receipts. It clearly distinguishes from siblings like hermes_api_jobs_pause and hermes_api_jobs_run, though it doesn't explicitly name alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this applies to 'previously paused' jobs, which implies the tool is for resuming paused jobs specifically. However, it doesn't name sibling alternatives (like hermes_api_jobs_run) or explicitly say when NOT to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the behavioral detail that it "writes redacted receipts," which is useful context beyond the annotations. It doesn't describe pagination behavior or return format, but there is an output schema to cover return values. A 3 is appropriate given the annotations carry much of the load.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly written sentence that states the HTTP method, endpoint path, and purpose. Zero wasted words. Front-loaded with the operation type and target resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET list tool with full (100%) schema coverage, an output schema present, and rich annotations (readOnly, idempotent, openWorld), the description covers purpose and side effects (redacted receipts). The sibling tools are numerous and mostly mutations; this simple read tool needs little more. The "redacted receipts" note adds functional context. Complete as-is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (limit, offset, category) are fully documented in the schema. The description adds nothing about parameters beyond noting it's a GET wrapper. Baseline 3 applies since the schema does the heavy lifting. Notably, the schema even discloses that category is 'reserved and ignored by the server,' which is more transparent than the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Typed GET /v1/skills wrapper that lists available skills" provides a specific verb (lists), resource (skills), and underlying operation (GET /v1/skills). It distinguishes from siblings like hermes_skill_read (reads a single skill) and hermes_skills_list (similar but without the API server target). The 'configured Hermes API server' context clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor any exclusions. It is implicitly a listing tool for skills from the Hermes API server, which contrasts with the many mutation/management siblings. However, there is no explicit when/when-not guidance or named alternative tools. Guidance is only implied by the read-only GET nature.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, giving a strong safety profile. The description adds the useful behavioral detail 'writing redacted receipts,' which reveals a side effect (receipt logging) not covered by any annotation. This is meaningful added context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core purpose ('Typed GET /v1/toolsets wrapper'), and includes the key behavioral detail (redacted receipts). Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There's an output schema present, so return values need not be described. Annotations cover the safety profile, and the schema covers all 3 parameters. The description competently handles this simple list tool. Slight deduction for not clarifying the 'currently reserved' status of parameters in the description itself, but the schema already conveys that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. Each parameter (limit, offset, category) is already well-documented in the schema with descriptions and default values. The description adds nothing about parameters beyond what the schema provides, but it doesn't need to given full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Typed GET /v1/toolsets wrapper that lists available toolsets') and clearly distinguishes it as a list operation. It doesn't explicitly distinguish from sibling tools, but the purpose is unambiguous enough that an agent would correctly identify this as a list/catalog operation. It's clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this vs alternatives like hermes_api_skills_list or hermes_profiles_list. It doesn't mention any exclusions or alternatives. A line about when one might prefer this over other list tools would substantially help.
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?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds the valuable constraint 'performs no git, service, or config mutation' which clarifies the non-destructive nature beyond the annotations. However, it doesn't describe what the proposal artifact looks like, whether it requires authentication, or what happens to existing proposals (overwrite vs append). With annotations already clarifying the safety profile, the description adds marginal but useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys purpose and safety characteristics without waste. It's front-loaded with the core purpose ('Write a proposal-only deploy repair artifact') and appends the crucial constraint. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, 0% schema coverage, no enums, and an output schema present (which the description need not explain), the tool is moderately complex. The description captures the core intent and safety posture but omits guidance on how deploy guard evidence is provided, which system/context this operates in, or what the produced proposal contains. For a proposal-generation tool paired with a separate apply tool, some handoff context would strengthen completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description mentions zero parameters. All 9 parameters (live_checkout, home, profile, toolkit_root, expected_branch, expected_commit, source_checkout, require_clean_live, compare_source_head) are documented only in the input schema. With 0% coverage, the description should compensate by explaining key parameters, but it offers no parameter guidance at all. Baseline 3 is slightly generous given zero compensating text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Write a proposal-only deploy repair artifact based on deploy guard evidence' with a specific verb (write), resource (deploy repair artifact), and scope (proposal-only, based on deploy guard evidence). It distinguishes itself from the sibling 'hermes_deploy_repair_apply' which handles actual application. Does not explicitly name the applying sibling, but the proposal-only contrast is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states this tool performs 'no git, service, or config mutation', which effectively differentiates it from hermes_deploy_repair_apply and other mutation tools. It's based on 'deploy guard evidence', clarifying that it should be used after deploy guard check output. However, it doesn't explicitly name the alternative (hermes_deploy_repair_apply) or state when NOT to use it, and doesn't describe prerequisites like running deploy_guard_check first.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety/profile via structured data. The description adds the process-local scope constraint and the fact it returns artifact/result status, useful context. However, it does not disclose polling semantics (timeout behavior, whether it blocks, polling rate) or what happens if the job_id is unknown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence that states verb, resource, scope, and return value with zero filler words. It is appropriately front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich output schema and four parameters, including three optional configuration params (home, profile, toolkit_root) that are wholly unexplained. With an output schema present, return-value documentation is less critical, but the polling semantics, process-local scope detail, and optional parameter purpose are gaps. For a tool of this complexity, the description is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for the 4 parameters. The description names job_id/run_id, which maps to the required parameter and confirms it's the ID to poll. However, the three optional parameters (home, profile, toolkit_root) receive no explanation of what they configure or when they're needed. With 0% coverage and only one of four params implicit, this is partial but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Poll') with a clear resource ('process-local Hermes Toolkit MCP async eval job') and states what it returns ('current artifact/result status'). It distinguishes from siblings reasonably — hermes_api_jobs_get is a generic REST API job getter, while this one is process-local async eval status. However, it doesn't explicitly differentiate from hermes_api_runs_get or the kanban run getters, and the 'process-local' qualifier may be ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies polling/status-checking context ('Poll... and return current status'), which gives the agent a sense of when to use it (after an async job is launched). But it does not state when NOT to use it or name alternative tools, such as hermes_api_jobs_get for REST jobs or hermes_api_runs_get for runs. No prerequisites are mentioned (e.g., that the job must be process-local).
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, giving a clear safety profile. The description adds context that it 'writes redacted receipts', which hints at side-effect logging, but doesn't elaborate on what those receipts are, where they go, or why the read-only operation writes anything at all — a slightly confusing behavioral disclosure that could use more explanation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, efficiently front-loaded with the core purpose. The 'writing redacted receipts' clause is a meaningful behavioral detail packed into the same sentence without waste. It's concise and earns its place, though the receipts clause could arguably be split for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema present, so return value detail is handled elsewhere. Annotations cover the safety profile (read-only, idempotent, non-destructive), and the empty schema means no parameter documentation burden. The description covers the data source and the receipt-writing side effect. This is reasonably complete for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (there is nothing to document). The description adds value by clarifying the exact source (dashboard.kanban preferences in config.yaml) and the behavior (writes redacted receipts), which is more than what the empty schema conveys. With 0 parameters, the baseline is 4, and this description meets it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads dashboard.kanban preferences from config.yaml and wraps a typed GET endpoint. The verb 'reads' plus the specific resource (dashboard.kanban preferences) distinguishes it from the many sibling kanban tools focused on tasks, boards, and links. However, it doesn't explicitly differentiate from similar config-read tools like hermes_config_summary or hermes_config_compare_surfaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates what it does (reads kanban config) but provides no explicit when-to-use or when-not-to-use guidance. It doesn't name alternatives like hermes_config_summary or hermes_config_compare_surfaces for broader config reading, nor does it clarify when retrieving the raw dashboard.kanban preferences specifically would be preferable.
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?
Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false — the safety bars are loosed, so the burden falls on the description. The description does well here: it discloses that this invokes an auxiliary LLM, writes 'redacted receipts', creates children, links the root, and flips triage to todo — revealing side effects and writing behavior beyond the annotation defaults. This is meaningful context, though it doesn't cover auth requirements or non-redacted data handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single packed sentence that conveys the full flow: POST wrapper, auxiliary LLM, task graph, children creation, linking, triage flip, and redacted receipts. It's dense but front-loads the core action. No wasted words or filler sentences. Slightly over-packed but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (so return values are documented elsewhere) and clear param schema. The description captures the main behavioral chain well. However, given this is a mutation tool with no readOnlyHint and involves an LLM call (implying potential for side effects, latency, nondeterministic output), the description could add more on failure modes, mutation scope (what 'redacted' implies about persisted data), or when decomposition is allowed. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the schema already documents 'id' as 'Kanban task id such as t_xxxxxxxx' and 'board' as 'Board slug for the task lookup. Defaults to the configured default board.' The description adds no parameter-specific semantics beyond what the schema provides. Baseline 3 is correct when schema does the heavy lifting and the description doesn't add param detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'runs the kanban decomposer auxiliary LLM to produce a task graph, create children, link the root, and flip triage to todo.' This is a specific verb+resource with clear scope. It distinguishes from siblings like hermes_kanban_task_specify (which likely specifies rather than decomposes) and hermes_kanban_task_update. However, it doesn't explicitly name an alternative sibling for differentiation, keeping it at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (decompose a kanban task into a task graph) but provides no explicit when-to-use guidance, prerequisites, or exclusions. There's no mention of when decomposition is appropriate vs. when to use specify/update/create. With a large sibling set of kanban tools, vague implied usage leaves room for an agent to misuse it. No alternatives are named.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds the detail of 'writing redacted receipts,' which is useful side-effect context beyond annotations. However, it doesn't describe output shape, pagination, or whether heartbeat data indicates liveness vs. staleness. Adds some value over annotations but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core action. The phrase 'Typed GET /api/plugins/kanban/workers/active wrapper' is slightly redundant with the name, but the rest (what it returns and the redacted-receipt side effect) earns its place. Marginally verbose but compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 0 params, an output schema, and read-only annotations, so the description's main obligations are covered. The redacted-receipt side effect and the fields returned are stated. For a zero-parameter list tool, this is reasonably complete. Could add when staleness/heartbeat interpretation matters, but that's a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters and schema coverage is 100%, so the description has nothing to document here. With zero parameters and an output schema present, the baseline of 4 is appropriate — there are genuinely no params to explain and the description correctly doesn't invent any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('lists currently spawned Kanban workers') with clear scope metadata (PID, profile, task id, heartbeat). It clearly distinguishes this from the broader hermes_kanban_* tools in the sibling list, particularly from run/dashboard tools. Minor deduction: 'Typed GET... wrapper' jargon adds little value for the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the read-only inspection tool for live workers, but doesn't explicitly name alternatives or exclusion cases (e.g., when to use hermes_kanban_orchestration_get or hermes_kanban_run_get instead). Given the large sibling set, some when-not guidance would help, but the read-only nature is reasonably inferable.
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 explicitly discloses the tool's safety profile: 'proposal-only', 'performs no skill writes or git operations'. Notably, annotations already include destructiveHint=false and the name contains 'proposal', but the description adds value by explicitly stating it creates artifacts (proposal) and does NOT write to skills or git — meaningful behavioral context beyond the annotations. However, it doesn't disclose what the output/return value looks like, and the output schema exists but the description doesn't reference it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key information: 'proposal-only' and 'no skill writes or git operations'. Every phrase earns its place and there is zero wasted text. It could arguably add a sentence on the replacement semantics (old_string/new_string matching), but as-is it's a compact, well-structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, an output schema, and a moderately complex read-modify-propose workflow, the description is somewhat thin. It doesn't explain the source resolution hierarchy (home/source/profile/toolkit_root), the matching semantics of old_string (first vs replace_all), or what happens if the old_string isn't found. The output schema exists but the description doesn't describe the proposal artifact format. The safety framing is good, but for a proposal-generating tool with this parameter surface, more operational guidance is warranted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description adds no parameter documentation. With 9 parameters, including a required old_string/new_string pair and optional home/source/profile/toolkit_root for locating the skill, the description does not explain how these relate to the readback or what source resolution means. The 'bounded skill-file readback' mention hints at a workflow but doesn't clarify parameter semantics. Baseline 3 is appropriate since the schema itself is reasonably self-explanatory for the required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Write proposal-only skill patch artifacts after bounded skill-file readback; performs no skill writes or git operations.' This uses a specific verb+resource ('write skill patch proposal') and explicitly distinguishes itself from the sibling tool hermes_skill_patch_apply by noting it is 'proposal-only'. It lacks some depth (doesn't mention that readback is a prerequisite step the agent must complete), but the core purpose is clear and differentiates from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the 'proposal-only' framing and the prerequisite 'bounded skill-file readback'. However, it doesn't explicitly state when to choose this vs. hermes_skill_patch_apply, or what distinguishes a proposal from an application scenario. The 'performs no skill writes or git operations' clause implicitly tells the agent this is the safe/preview variant, but excluding the apply sibling by name leaves guidance implicit rather than explicit.
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?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds the 'without reading secrets' scoping constraint, which is valuable behavioral context. However, it doesn't describe what the return output looks like or whether the summary reflects current vs. on-disk state, though an output schema exists. The non-secret guarantee is genuinely useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence that enumerates the full scope of what's summarized and includes the critical safety qualifier 'without reading secrets'. No filler words, no redundancy, front-loaded with the action verb. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a read-only info/summary aggregator with an output schema present and all parameters optional with 100% schema coverage, the description is reasonably complete. It covers scope and the security constraint. It could benefit from noting whether this touches the network or reflects live state, but for an info summarizer the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented in the schema with their constraints (home, profile, toolkit_root each with allowed-root path restrictions). The description adds one meaningful behavioral detail: the summary spans agents, skills, eval harness paths, suites, helper scripts, and README metadata. With full schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Summarize') and enumerates the exact resources covered (agents, skills, eval harness paths, suites, helper scripts, README metadata), which clearly distinguishes it from sibling tools. It's not a bare tautology. However, it doesn't explicitly compare against closely-related siblings like hermes_skills_list or hermes_config_summary, and the dashboard-like aggregate nature isn't contrasted with the more targeted list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly scopes what it covers but provides no when-to-use guidance or mention of alternatives. Context signals show all 3 parameters optional and readOnlyHint=true, implying a safe summary view, but there's no explicit 'use this instead of hermes_skills_list when...' guidance. The 'without reading secrets' clause is a useful safety qualifier but not a usage context for agent decision-making.
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 readOnlyHint=true and destructiveHint=false already in annotations, the description adds meaningful behavioral context beyond annotations: it discloses redaction behavior ('redacting secret values') and env presence-only reporting. This explains privacy/safety behavior the annotations alone cannot convey, which is genuinely useful for an agent deciding whether to call this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One well-structured sentence that front-loads the core purpose and appends the redaction behavior as a modifier. Zero wasted words. Could arguably be a 5, but it reads as one long sentence rather than being broken into scannable chunks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With readOnly/idempotent annotations, 100% param coverage, and an output schema present, the description's job is lighter. It adequately covers the read semantics, redaction behavior, and MCP transport metadata focus. An output schema exists so return format doesn't need to be described. Complete enough for an optional-param inspection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the three parameters (home, profile, toolkit_root) are already well described with constraints (patterns, allowed roots). The description mentions 'redacting secret values and reporting env presence only' but doesn't add param-specific semantics beyond what schema provides. Baseline 3 is appropriate since the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific compound verb-noun phrase ('Read Hermes config shape and MCP server transport metadata') that clearly identifies the resource and scope. It doesn't explicitly name sibling alternatives, but 'config summary' is itself distinctive among many config/summary-related siblings like hermes_config_patch_apply and hermes_config_compare_surfaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a read-only inspection surface (summarizing config shape), which contrasts it from write-oriented siblings like config_patch_apply. However, it never explicitly states when to use this tool vs the several other overview/status tools (hermes_status_overview, hermes_gateway_status, hermes_toolkit_info), leaving the agent to infer the differentiation.
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?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile well. The description adds meaningful context beyond annotations: 'writing redacted receipts' discloses an internal side effect (logged output), and 'Typed GET wrapper' clarifies it's a read operation. This adds value without contradicting 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient sentence that packs purpose, mechanism (typed GET wrapper), scope (optional board-scoped task counts), and a notable side effect (writing redacted receipts). No wasted words, appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single optional parameter, full schema coverage, an output schema present, and strong annotations (read-only, idempotent, non-destructive), the tool is well-specified. The description's mention of 'redacted receipts' addresses an element not in annotations or schema. Minor gap: doesn't clarify what a 'receipt' is or why the side effect matters to the caller, but overall complete given the simple surface.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with only one optional parameter (board). The schema already documents 'Board slug to query. Defaults to the configured default board.' The description adds the concept of 'board-scoped task counts' which relates to the board parameter, providing mild extra context, but the schema largely carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: lists available assignee profiles via a wrapper around GET /api/plugins/kanban/assignees, with optional board-scoped task counts. Verb+resource is clear. While it doesn't explicitly distinguish from siblings, 'assignees' is unique among the kanban tools, and the 'writing redacted receipts' detail adds distinguishing scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need to see assignee profiles) but doesn't explicitly state when NOT to use it or name alternatives. It notes 'optional board-scoped task counts' giving some usage context. No explicit exclusion or alternative tool 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?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, which cover the safety profile well. The description adds value by disclosing that output is redacted, that it's a 'typed wrapper' of a specific GET endpoint, and that process control remains unwrapped/denied — useful behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both substantive, covering endpoint, data read, redaction behavior, and process-control boundary. No redundant filler. Slightly technical ('Typed GET...wrapper') but efficient and front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only inspection tool with strong annotations (readOnlyHint, idempotentHint, destructiveHint=false), an output schema, and one fully-described parameter, the description is reasonably complete. It discloses redaction and process-control denial, which are key behavioral facts. Combined with the good annotations, this is adequate for safe agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description ('Kanban run id to inspect, e.g. 741 or run_xxxxxxxx') already documents the single required parameter with format examples. The description adds minimal param meaning beyond identifying that it reads run output, so baseline 3 is appropriate given the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('reads per-run captured output') and clearly distinguishes the tool's scope as a read-only inspection of run output. It does distinguish from siblings somewhat by specifying the read-only inspect nature and that process control remains denied/unwrapped, though it doesn't name an alternative tool explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool reads ('per-run captured output with stdout/stderr preview, redacted') and notes that process control is denied, giving some context. However, it doesn't explicitly tell the agent WHEN to choose this over alternatives like hermes_kanban_run_get or hermes_api_runs_get, nor what distinguishes it from other run-related tools.
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 that it 'runs the triage specifier auxiliary LLM' (an important side effect — LLM invocation, cost/latency implications) and states it 'writes redacted receipts' (a side effect beyond the core operation). Annotations provide readOnlyHint=false, openWorldHint=true, and it's not destructive/idempotent, but the description adds meaningful behavioral detail about executing a nested LLM and writing receipts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence that packs the endpoint type, operation, mechanism, effect, and a side effect (receipts). Efficient and informative, though slightly jargon-heavy ('triage specifier auxiliary LLM', 'redacted receipts' could use a touch of expansion). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a good description, 100% parameter coverage, an output schema present, and only 2 params, this is fairly complete. The description covers the mechanism, the state transition, and a notable side effect. Minor gaps: no mention of what 'receipts' are used for or potential failure cases when the auxiliary LLM output is low quality, but these aren't blocking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both id (task id format) and board (slug, default) are documented in the schema. The description mentions the endpoint path but adds no parameter semantics beyond what the schema already provides, which meets the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb (specify/promote), resource (Kanban triage task), and key effect (flesh out a triage task and promote it to todo). It distinguishes from sibling hermes_kanban_task_create/update/decompose by describing the specific 'specify' pathway through the triage specifier LLM. However, it doesn't explicitly name a differentiated sibling function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for triage tasks being promoted to todo via an auxiliary LLM, which gives some context. It does not state when NOT to use it versus task_update or task_decompose, nor when one would choose this over alternatives. The context is implied rather than explicit.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds behavioral context about 'bounded reads' and 'redaction' behavior, plus the allowlist restriction that governs access. However, it doesn't disclose what happens on denied paths (error? empty output?) or the return format details despite having an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that packs purpose, constraints, and exclusions. No wasted words. The 'configured allowlisted' qualifier plus 'bounded reads and redaction' plus 'arbitrary log paths are denied' conveys the full operational contract economically.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, 0% schema coverage, an output schema present, and readOnly/idempotent annotations, the description provides the core security contract (allowlisted only) but doesn't explain several parameters (home, profile, toolkit_root) or how a user determines which log_name values are valid. The output schema exists so return values don't need description, but param guidance and log discovery are incomplete for a 6-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. However, it only adds meaning for the overall operation (bounded reads/redaction) without explaining individual parameters. The schema already documents defaults (lines=80, max_bytes=65536) and constraints (max 500 lines, 1MB), but the description doesn't clarify what log_name must match or how to find valid allowlisted log names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('tail') plus resource ('configured allowlisted log path') and adds scoping constraints ('bounded reads', 'redaction'). It distinguishes from siblings since the 'allowlisted' restriction makes clear this is not a generic file-reading tool. However, it doesn't explicitly reference sibling differentiation or describe what 'Hermes log' means concretely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when the tool is usable: 'configured allowlisted log path' and explicitly says 'arbitrary log paths are denied,' providing a clear exclusion criterion. It implies the alternative (that arbitrary paths aren't allowed and you must use allowlisted ones) without naming specific sibling tools. This gives reasonable context for when to use vs not use.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds value by disclosing path resolution behavior and root-bounding constraints, which are meaningful behavioral details not present in annotations. It also implies a max_bytes limit via the schema, but the description itself doesn't mention truncation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with zero waste. Every word contributes to understanding scope and constraints. Front-loaded with the primary action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, 0% schema coverage, and an output schema, the description should explain how the skill location resolution works across source/home/profile/toolkit_root since these determine which skill file gets read. The resolved-path concept is hinted but not elaborated. The description is adequate for basic understanding but leaves location semantics unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and there are 7 parameters. The description mentions 'skill' and 'linked file' which map to skill_id and file_path, but doesn't explain the meaning of source, home, profile, or toolkit_root — parameters that distinguish how the skill is located. With 0% schema coverage, the description must compensate for these but only partially does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool reads 'one bounded SKILL.md or linked skill file' after resolving the skill and linked file within allowed roots. The verb 'Read' plus resource is clear, and the mention of bounded/root resolution adds specificity. It doesn't explicitly distinguish from siblings, though siblings include read-like tools (hermes_api_docs_read), so differentiation is somewhat implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'within allowed roots' and 'bounded' implies there are constraints on what can be read, providing some security context. However, it doesn't explicitly state when to use this tool versus the many siblings (e.g., hermes_skills_list for listing, hermes_api_skills_list, hermes_skill_eval_start). No explicit exclusions or alternatives are named.
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?
Annotations provide destructiveHint=false and readOnlyHint=false, but the description clearly signals destructive behavior by saying 'removes a scheduled Hermes cron job and cancels any in-flight run'. It adds context beyond annotations by specifying that in-flight runs are canceled and that 'redacted receipts' are written. However, it doesn't disclose permission requirements, whether removal is reversible, or consequences for dependent resources. Notable: destructiveHint=false seems optimistic given the description, but doesn't directly contradict since the hint is false (not destructive), while the description says it removes a job—this is a mild tension but not a direct contradiction of a readOnly write claim.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that packs endpoint, verb, purpose, and side effects (cancels in-flight run, writes redacted receipts) into a compact form. Zero wasted words and front-loaded with the most important semantic content. Ideal length for this simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to explain return values. The tool is simple (1 param, no nesting, 100% schema coverage). The description covers the core action, a side effect (in-flight cancellation), and output behavior (redacted receipts). Given the tool's simplicity and the structured data already available, this is reasonably complete, though it could optionally mention authentication requirements or idempotency behavior for repeated deletes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter (job_id has 'Unique job identifier' and min/max length constraints). The description adds the endpoint path detail (/api/jobs/{job_id}) which connects the parameter to the HTTP URL, a slight value-add. With full schema coverage and only one simple parameter, the description doesn't need to add much, but it also doesn't explain what kind of identifier job_id is (UUID vs name) or format expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource ('Typed DELETE /api/jobs/{job_id} wrapper that removes a scheduled Hermes cron job'), including the exact HTTP endpoint. It distinguishes itself from siblings like hermes_api_jobs_pause, hermes_api_jobs_resume, and hermes_api_jobs_run by making the destructive removal semantics explicit. The title 'Delete Hermes scheduled job' reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when a job needs removal), but does not explicitly state when NOT to use it or name alternatives like pause (temporary halt) versus delete (permanent removal). Among the many sibling job-related tools, there's no explicit exclusion guidance distinguishing delete from pause/resume/run. The context of 'removes' and 'cancels in-flight run' gives reasonable implied usage but no explicit alternatives.
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?
The 'writing redacted receipts' detail is a useful behavioral disclosure about side effects. However, with annotations declaring readOnlyHint=false, the agent already knows this mutates state. The description doesn't address what 'redacted receipts' implies, whether updates are reversible, or any permission/auth requirements. It adds some context but lacks depth for a state-changing 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the HTTP method, path, and action, then enumerates the updatable fields. Zero waste, every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and 8 parameters where 6 are nullable optional fields, the description covers the core semantics (partial update of specific fields). The 'redacted receipts' note hints at response behavior. This is reasonably complete for a well-scoped REST update wrapper, though it could mention idempotency or prerequisite job existence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only job_id and enabled have descriptions), so the description partially compensates by listing editable fields (prompt, schedule, skills, provider/model, delivery, enabled). However, it doesn't clarify nuances like whether setting enabled=false is equivalent to pause, or format requirements for schedule/deliver. The description maps field categories but doesn't add syntax details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states this is a typed PATCH /api/jobs/{job_id} wrapper that partially updates a scheduled Hermes cron job, and lists updatable fields (prompt, schedule, skills, provider/model, delivery, enabled). This clearly distinguishes it from sibling tools like create/delete/get/pause/resume/run, though it doesn't explicitly name them as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is a 'partial update' operation, distinguishing it from create, delete, pause, resume, and run siblings. However, it doesn't explicitly state when NOT to use it (e.g., for pausing/resuming use dedicated tools) or mention lifecycle context like needing an existing job_id first.
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?
The description states it 'deletes' a stored response (consistent with the DELETE verb), includes the note about 'writing redacted receipts' (useful side-effect context), and references the configured server. However, annotations mark destructiveHint=false despite 'delete' semantics, and the description doesn't clarify whether this is a true destructive delete or something safer. It doesn't address auth requirements or failure 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single compact sentence that captures the HTTP method, resource path template, purpose, and a noteworthy side effect (redacted receipts). Efficient and front-loaded with the verb/DELETE and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward single-parameter DELETE wrapper with 100% schema coverage and an output schema present, so the description does not need to be extensive. It covers the core action and the notable redacted-receipt behavior, which is adequate for the low complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single response_id parameter fully documented in the schema ('Stored response id to delete'). The description adds no new parameter info beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (DELETE), the resource path (/v1/responses/{id}), and the action (delete a stored response). It clearly distinguishes from siblings like hermes_api_responses_get and hermes_api_responses_create by identifying the destructive counterpart operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly signals this is a delete operation on a specific response, but it does not state when to prefer it over alternatives, mention that get/create would be used for other purposes, or note any prerequisites (e.g., the response must exist). No explicit 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by clarifying the aggregation scope (install, profile, toolkit, config, API config metadata) and the constraint of no prompt-bearing calls. No annotations are contradicted, and the description aligns with the read-only/idempotent framing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero waste, front-loaded with the verb and scope. Every element — the five metadata categories and the 'without live prompt-bearing calls' exclusion — earns its place and adds meaningful information in compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return value documentation) and strong annotations (readOnly, idempotent, non-destructive), plus 100% schema coverage on parameters, the description is largely complete for an aggregate-status tool. The exclusion of prompt-bearing calls is a valuable behavior note. It could benefit from hinting what consumers might do with the data, but this is minor given the strong structured coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (home, profile, toolkit_root) already documented in the schema including constraints like 'Must resolve under configured allowed roots' and pattern validation. The description adds no parameter-specific meaning beyond the schema, so baseline 3 is appropriate. The description's scope language (install, profile, toolkit) maps loosely to the parameters but doesn't add syntax or format detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('aggregate') with an explicit resource scope ('read-only Hermes install, profile, toolkit, config, and API configuration metadata'). It clearly differentiates itself from siblings by emphasizing 'without live prompt-bearing calls', which distinguishes it from tools like hermes_gateway_status or hermes_api_smoke. The scope delineation across five metadata categories is precise and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it avoids 'live prompt-bearing calls', implying this is a safe/read-only overview tool compared to action-oriented siblings, which gives implicit usage context. However, it doesn't explicitly say when to prefer this over related siblings like hermes_detect_install, hermes_toolkit_info, or hermes_config_summary, nor does it state when NOT to use it. The distinction is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which tells the agent this is a safe, non-mutating read. The description adds genuine value beyond annotations by disclosing the 'writing redacted request/result/response receipts' side-effect, which is non-obvious behavioral context that the idempotent/readOnly hints don't fully convey. This is useful transparency beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that packs the method, endpoint resource, purpose, scope, and the receipt-writing side-effect into compact phrasing. It's front-loaded with the main purpose. Slight negative: 'writing redacted request/result/response receipts' is cryptic and could be more plainly stated (what are receipts, where are they written?), but as a concise clause it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, 100% parameter schema coverage, and comprehensive annotations declaring it non-destructive, idempotent, and open-world. Given this rich structured context, the description's job is light: it adds the GET /v1/models method mapping and the redacted receipt-writing behavior. This is reasonably complete for a simple single-parameter list tool with strong annotation coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single parameter 'include_internal' with a clear description. The description doesn't elaborate further on parameter semantics, but with 100% coverage and only one boolean parameter, the schema does the heavy lifting adequately. Baseline 3 is appropriate since the description adds no additional parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource structure: 'lists available models from the configured Hermes API server.' It clearly states what is returned (available models), the source (Hermes API server), and the method (GET /v1/models wrapper). It also discloses a side-effect behavior (writing receipts) that distinguishes it from simpler list operations. Among siblings like hermes_api_skills_list and hermes_api_toolsets_list, the resource is unambiguously identified as models.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about what the tool does and its scope ('from the configured Hermes API server'), implying appropriate usage when one wants to enumerate available API models. However, it does not explicitly state when NOT to use this tool or name an alternative, and there are many read-only list siblings that could overlap in purpose. No exclusions or preferential-use guidance is provided.
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?
Annotations provide readOnlyHint=false (mutation), openWorldHint=true (external side effects), no idempotency, no destruction. The description adds meaningful context beyond annotations: gate requirements, streaming disabled, chaining support, and that it 'writes redacted request/result/response receipts' — useful side-effect disclosure for an openWorld tool. It doesn't contradict annotations. Misses mention of side effects on external model calls explicitly, though openWorldHint covers this partially.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single dense sentence that packs substantial information: endpoint wrapper type, gate requirements, streaming limitation, chaining support, and receipt writing. It's efficient and front-loads the core purpose. Slightly crammed with policy/gate jargon but each clause carries distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create-type API wrapper with 8 well-documented params, an output schema present, and annotations covering safety/effects, the description is reasonably complete. It adds gate requirements and side-effect (receipt writing) context beyond structured fields. Could elaborate on what the response object contains or when output schema validates, but with output schema present, the description need not explain return values. Adequate coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the 8 parameters having its own description. The tool description adds a bit on top: 'Array content parts are not supported in v0' (in the input schema itself), chaining semantics tied to previous_response_id/conversation. However, most parameter behavior is already in the schema. Baseline 3 is appropriate when schema does the heavy lifting; description adds marginal context like 'store' default enabling later chaining.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Typed OpenAI Responses API POST /v1/responses wrapper' with a clear verb (create) and resource (Hermes API response). It summarizes key features including gate requirements, streaming, chaining, and receipt writing. It doesn't explicitly distinguish from sibling create tools like hermes_api_jobs_create or hermes_kanban_task_create, though the name and RESPECTIVE prefix make the API-response relationship obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys prerequisites ('Requires api_call policy plus live/model/tool/external-side-effect gates') and behavior constraints ('disables streaming in v0', 'supports previous_response_id / conversation chaining'). It communicates the wrapper nature, but doesn't explicitly state when NOT to use this versus alternative creation tools like hermes_api_jobs_create or hermes_api_chat_completions, leaving the choice somewhat to the agent.
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?
Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds meaningful context: that this action writes redacted receipts and requires external-side-effect gates, revealing side-effect behavior beyond the bare annotation flags. It discloses the permission tier. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that packs the API route, action, side effects, and auth gates efficiently. Every clause earns its place. It could arguably be split for readability, but the length is appropriate and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and 100% parameter coverage, so the description doesn't need to explain return values or parameters. Given this is a state-mutating approval action (not read-only), the description does enough by disclosing side effects (redacted receipts), auth tier, and gates. Slightly more detail on the relationship between approved/scope/note semantics would push this to 5, but given the rich structured data available, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 4 parameters (run_id, approved, note, scope) are documented in the schema. The description adds the high-level context that this 'submits an approval decision' and mentions receipts, but doesn't elaborate on parameter semantics like how scope interacts with approved=false or what approved=false with scope means. Baseline 3 is appropriate given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a typed POST wrapper that submits an approval decision for a paused Hermes run, writing redacted receipts. The verb is specific (submit approval decision) and the resource is clear (paused run). It doesn't explicitly differentiate from siblings, but the 74 sibling tools are mostly unrelated API operations, so a dedicated approval action is self-evident in 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it requires 'api_call tier with live, agent-tool, and external-side-effect gates' which gives the agent clear authorization context. However, it doesn't explicitly say when NOT to use it or name alternatives. The approval-vs-run-context is implied by the word 'paused' but not elaborated as an explicit condition.
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 carrying behavioral safety info (readOnlyHint=false, destructiveHint=false), the description carries the burden and does disclose meaningful behavior: it is synchronous, writes artifacts (request/result/summary/stdout/stderr/report), requires specific environment/policy gates for live eval. It doesn't mention whether it leaves persistent state or what happens to prior artifacts, but it covers the key behavioral surface.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero padding. The most important operational constraints (synchronous, artifact-producing, live-eval gating) are front-loaded. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema present, which relieves the description of return-value documentation. However, given 12 parameters with 0% schema coverage and no annotation support, the description leaves significant gaps: it doesn't explain which parameters matter for which use cases, what 'bounded' means for time/resource limits, or how backend options differ. For a complex eval-run tool, this is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for 12 parameters. The description references live_eval and the harness but doesn't explain semantics for parameters like backend, workers, judge_model, profile, home, or timeout_seconds. It adds minimal parameter-level value beyond identifying that live_eval gates behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs a bounded Hermes eval suite synchronously through the configured harness. It distinguishes itself from related siblings like hermes_eval_start (non-synchronous start) and hermes_skill_eval_start. However, it doesn't explicitly contrast with the sibling eval tools, and 'bounded' is a term that isn't further clarified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear prerequisites for live evals (live_eval=true, HERMES_TOOLKIT_MCP_ALLOW_LIVE_EVAL=1, and the policy gates), and notes that dry/structural suites don't require live-model opt-in. This gives agents practical when-to-use guidance, though it doesn't explicitly name alternative tools for the non-live case or exclude when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful context about the side-effect gating, policy tier requirement, and redacted artifact capture. The description complements rather than contradicts annotations, adding value about what conditions must hold and what output behavior to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single dense sentence that packs in the key constraints. It's somewhat jargon-heavy but efficient. Could be split for readability but earns its space given the complexity of the gating conditions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A destructive, side-effect-producing tool with 7 parameters, 0% schema coverage, and a high-risk operation. The description conveys the critical gating context (owner tier, external-side-effect, command hash, nonce) and notes output redaction. However, it doesn't explain what the return output looks like (though an output schema exists, which reduces this burden) or detail failure modes like what happens when gates aren't met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The description names some parameters implicitly (confirmation nonce, command hash) but does not explain semantics for all 7 parameters like home, profile, toolkit_root, or timeout_seconds. The confirmation_nonce and expected_restart_command_sha256 are mentioned by name in the description, which helps, but the optional path parameters remain unexplained. Baseline is 3 given low coverage and partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a preconfigured gateway restart command with multiple gating conditions. It distinguishes from siblings like hermes_gateway_status (status check) and hermes_deploy_repair_apply (repair) by specifying it's an actual restart action. Slightly dense phrasing but the verb+resource+scope is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a privileged action by specifying 'owner policy tier' and lists several gating requirements (external-side-effect, allow_gateway_restart, command-hash, confirmation nonce). This implicitly tells the agent this tool requires owner permissions and specific preconditions, distinguishing when to use it. However, it doesn't explicitly name alternative tools or state when NOT to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe-read behavior is fully covered by structured data. The description adds one behavioral detail: "writing redacted receipts," which is a meaningful side-effect disclosure (though the term 'receipts' is somewhat cryptic and unexplained). No contradiction with annotations; the description adds modest behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence that conveys the HTTP mapping, the resource read, the scoping parameters, and the receipt side-effect. Efficient and front-loaded with the core action (reads one Kanban task by id). The only minor issue is that 'writing redacted receipts' is an unexplained jargon term that may confuse an agent, but overall the description is compact and purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with an output schema present, full annotation coverage (read-only, idempotent, non-destructive), and 100% param schema coverage, the description is largely sufficient. The 'redacted receipts' behavioral note adds value, though an explanation of what receipts are or what the output schema returns would be more complete. Still, the combination of annotations + schema + description covers the tool's contract adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, board, tenant) already having a descriptive comment in the schema. The description's phrase "with optional board slug and tenant" clarifies the intended role of the two optional params—that they are scoping/namespacing qualifiers rather than filter criteria—adding interpretative value beyond the raw schema field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: "reads one Kanban task by id" with optional board slug and tenant. It identifies this as a wrapper for GET /api/plugins/kanban/tasks/{id}, clearly distinguishing it from sibling tools like hermes_kanban_task_create, update, and specify. The purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it requires an id and optionally accepts board slug and tenant, implying when these are needed for a successful lookup. However, it doesn't explicitly state when to prefer this over sibling read tools like hermes_kanban_run_get or hermes_kanban_board_get, nor does it note whether board/tenant are needed for namespacing versus optional scoping. Usage context is implied but not fully elaborated.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, which fully cover the safety profile. The description adds the offline/no-calls behavioral guarantee, which is a meaningful extra beyond annotations. It doesn't describe return format, error behavior, or what 'defaults to full' renders, but annotations carry most of the burden here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action, and every clause earns its place — the purpose, the offline guarantee, and the acceptable input formats are all conveyed in one tight sentence. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, offline docs-reading tool with a rich output schema and full parameter coverage, this is largely complete. Could mention what happens when no uri/section is provided (the 'full' default, which is only partially implied by the param schema's 'Defaults to full'). Minor gap given the tool is otherwise well specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (uri and section) are well documented in the schema itself. The description adds the default behavior ('Defaults to full'), which is a slight value-add but not substantially beyond what a good schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Read one bundled Hermes API server docs section by slug or resource URI'. Clearly distinguishes from siblings like hermes_api_docs_list and hermes_kanban_api_docs_read by explicitly naming the alternate resource format (hermes-docs://api-server/*).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States it operates 'without network, API, model, or tool calls', which is useful usage context. Also implicitly distinguishes from list tools via 'one section by slug'. However, no explicit when-to-use vs alternatives beyond the inherent read-versus-list distinction, and there's no explicit 'use this when X, use that when Y' guidance.
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?
Annotations only declare readOnlyHint=false, destructiveHint=false, leaving safety profile undisclosed. The description adds the async in-process behavior and the dry/live gate equivalence to hermes_eval_run, along with poll/cancel lifecycle. This is useful but doesn't disclose side effects, state changes, or what happens to the environment during the job, and no output format is described (though an output schema exists).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the primary action, and efficiently references the sibling tool for gates instead of re-explaining them. Zero filler words. The cross-referencing to hermes_eval_run is a good compression technique.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex (12 params, async job lifecycle). The description covers the key behavioral aspects: async, bounded, in-process, gates equivalent, and lifecycle via poll/cancel. It doesn't detail the output schema structure, but an output schema is present so the description needn't explain returns. The main gap is parameter semantics, but for an async launcher tool with a rich schema, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there are 12 parameters, so the description carries the burden. The description adds nothing about any parameter's meaning (home, model, backend, profile, workers, base_url, live_eval, hermes_bin, judge_model, toolkit_root, timeout_seconds). While parameter names are somewhat self-explanatory, the description doesn't explain distinctions like live_eval vs dry, or how backend/workers interact. The output schema exists but parameters remain under-documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('Start one bounded Hermes eval suite as an in-process async job') with clear scoping ('bounded', 'in-process'). Distinguishes from siblings by naming hermes_job_status and hermes_job_cancel for polling/cancellation. The async nature is clearly stated, differentiating it from the synchronous hermes_eval_run 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States it's an async job variant with the 'same dry/live gates as hermes_eval_run', which pairs it against a known sibling. Explicitly names the two companion tools for follow-up (hermes_job_status, hermes_job_cancel). However, it doesn't give explicit when-to-use vs when-not-to-use guidance versus the synchronous hermes_eval_run (e.g., large/long-running suites vs quick ones).
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered by metadata. The description adds context about what it does NOT touch (profile memory, skills writes, evals), which adds value beyond annotations. However, it doesn't describe output shape or pagination semantics, though it does have an output schema. With strong annotations, the description's additional 'non-operations' clarification earns a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the main operation ('List Hermes toolkit/profile skill directories'), adds a scoping qualifier ('and linked-file inventories'), and then efficiently enumerates exclusions. Zero waste, no redundancy with the title. Well-structured with the negation listing at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 optional parameters (none required), a rich output schema, and strong annotations. The description correctly focuses on the operation's scope and boundaries rather than repeating schema details. It's complete for a read-only list operation: clear purpose, clear exclusions, and the schema handles parameter semantics. Slight deduction for not mentioning pagination behavior explicitly, though limit/offset params cover this implicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden for parameter meaning. However, the parameter names in the schema (home, limit, detail, offset, profile, toolkit_root) are largely self-explanatory — 'limit'/'offset' clearly imply pagination, 'detail' has an enum of summary/full, 'profile' and 'toolkit_root' are path selectors. The description adds no parameter-specific detail beyond what the schema names convey, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: lists skill directories and linked-file inventories while explicitly excluding three operations (reading profile memory, writing skills, invoking evals). The verb 'List' plus 'toolkit/profile skill directories and linked-file inventories' is specific and resource-bound. It distinguishes from nearby siblings like hermes_skill_read and hermes_skill_eval_start by naming what it does NOT do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the scope and explicitly lists excluded operations (without reading profile memory, writing skills, invoking evals), giving the agent a good sense of safe use. It doesn't name explicit sibling alternatives for when a user needs something excluded, but the exclusions themselves serve as implicit guidance. Could be improved by pointing to hermes_skill_read for reading content or hermes_skill_eval_start for evals.
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?
Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes beyond these by disclosing that it 'writes private artifacts,' 'supports async jobs,' and 'may trigger live/model/tool side effects' (via risk_acknowledgement description). It is openWorld (outbound model calls), which aligns with openWorldHint. This adds meaningful behavioral context beyond annotations, though async/artifact behavior is partially implied by the schema structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence packs the purpose, gatekeeping requirements, artifact behavior, async support, and fallback warning into minimal prose. No wasted words. The front-loading ('Last-resort prompt bridge...') immediately orients the agent to the tool's exceptional nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 14 params, asynchronous operations (run/start/status/cancel), conditional required fields via allOf, gatekeeping fields, and behavioral side effects, the description covers the essentials reasonably well. An output schema exists. Gaps remain: it doesn't clearly enumerate the four distinct operations and their select semantics, but the schema's discriminator plus 86% param coverage partially covers this. Given the tool's complexity, slightly more operational guidance would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 86%, so most params are already documented. The description adds value by naming the required gatekeeping params (why_no_typed_tool_fits, docs_resource_consulted, typed_wrapper_checked, risk_acknowledgement, expected_evidence), clarifying their collective purpose as a safeguard checklist. It also clarifies that writes private artifacts and warns when a typed tool would be better, which influences how params like risk_acknowledgement should be filled.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a 'last-resort prompt bridge' to a Hermes Agent backend used 'after typed tools do not fit.' It names the verb+resource (prompt bridge to configured backend) and conveys its role as an escape hatch. However, it doesn't explicitly distinguish itself from the ~70 sibling typed tools by name, relying on the 'last-resort' framing and 'why_no_typed_tool_fits' requirement to imply differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it's used 'after typed tools do not fit' and 'warns when a typed tool would be better,' which provides clear context and exclusion guidance. It requires the caller to justify why no typed tool fits (via required params). However, it doesn't name specific alternative tools or give richer when-not-to-use scenarios beyond the generic 'prefer typed tools' framing.
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?
Annotations already cover readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds the valuable context that the tool 'writes redacted receipts', a meaningful side effect not captured by the annotations. It also confirms it's a typed GET wrapper. This complements the structured data without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, zero wasted words. Each clause earns its place: 'Typed GET' sets the call semantics, 'detailed health' indicates scope, and 'writing redacted receipts' adds the distinguishing side effect. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameter-free-ish GET health check (0 required params), with full schema coverage, rich annotations (readOnly, idempotent, openWorld), and output schema present, the description is complete enough. The redacted-receipts detail adds important behavioral context, and the output schema handles return value shape documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the one parameter (include) is fully documented in the schema with its enum values and description. The description adds 'detailed health' context but doesn't elaborate on parameter behavior. Per the rubric, baseline 3 is appropriate when the schema does the heavy lifting, which it does here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Typed GET /health/detailed wrapper that checks the configured Hermes API server detailed health, writing redacted receipts.' It has a specific verb+resource ('checks...detailed health'), identifies the endpoint type (GET /health/detailed), and adds the distinctive 'writing redacted receipts' behavior that differentiates it from the sibling hermes_api_health and hermes_status_overview tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this should be used for detailed health checks vs. the basic hermes_api_health, but doesn't explicitly state when to choose this over alternates. The detailed vs. overview distinction is implied by the name and 'detailed' keyword in the description, but no explicit when/when-not guidance or alternative tool names are given.
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?
Annotations declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile well. The description adds the behavioral detail that it 'writes redacted receipts' as a side effect of the GET, which is non-obvious and valuable context beyond what annotations provide. Minor omission: doesn't note whether reading impacts the job state (e.g., run counters).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single dense sentence that packs the HTTP method, endpoint, purpose, and side-effect in a compact form. Slightly overloaded semantically (typed GET, definition + state, redacted receipts) but no wasted words. Could be split into two sentences for readability but is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool fetches job definition AND last-run state, and an output schema exists. With strong annotations covering the safety profile, one simple param fully documented, and an output schema present, the description is adequate. The 'redacted receipts' side effect is noted. It could mention what the output schema includes, but the presence of an output schema reduces this burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter job_id is documented in the schema as 'Unique job identifier'. The description reinforces that job_id is the path segment target. The schema already covers the param semantics well; the description adds minimal value but the baseline of 3 applies, and the 'scheduled Hermes cron job' phrasing clarifies the resource type being referenced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states this is a GET wrapper over /api/jobs/{job_id} that retrieves a single scheduled Hermes cron job's definition and last-run state. It uses specific verb+resource, distinguishes well from siblings like jobs_list (all jobs), jobs_create/update/delete (mutations), and jobs_pause/resume/run (state changes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the read primitive for a single job, which is clear from naming, but there is no explicit when-to-use guidance or mention of alternatives like hermes_job_status or status_overview that might overlap. Sibling hermes_job_status suggests an alternative status view that isn't acknowledged.
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 readOnlyHint=true (marked false), no destructive hint, and no idempotent hint, annotations provide limited safety info. The description adds the key behavioral detail that this is non-streaming and that it 'writes redacted receipts' as a side effect—valuable context not covered by annotations. It doesn't detail auth requirements or rate limits, but the receipt-write disclosure is useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences with no waste. The most important facts—it's a typed GET events wrapper, non-streaming, writes redacted receipts—are front-loaded. Could arguably add a sentence about what kinds of events are returned, but it's appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (present) and full param coverage, so the description doesn't need to explain return structure. The non-streaming clarification and 'writing redacted receipts' side effect add important context. It's reasonably complete for a read-oriented events tool, though it could mention pagination behavior via the 'after' cursor more prominently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters (run_id, after, limit, include) already have descriptions in the schema (cursor opaque, max events, event kinds enum, run id format). The description itself adds minimal parameter meaning beyond noting it returns 'non-streaming event metadata.' Baseline 3 is appropriate given the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a typed GET /v1/runs/{run_id}/events wrapper returning non-streaming event metadata for a Hermes run. It explicitly distinguishes itself from a streaming SSE/WebSocket proxy, which separates it clearly from the large sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'not a streaming proxy,' establishing when NOT to use it (streaming scenarios). Among siblings like hermes_api_runs_get and hermes_api_runs_start, this one's job of fetching event metadata is reasonably clear. It doesn't name specific alternative tools but the 'not streaming' exclusion helps 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?
Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds beyond these: it discloses the specific side effect of writing redacted request/result/response receipts, and specifies the permission gates (api_call tier with live, model, agent-tool, external-side-effect gates). This adds meaningful behavioral context about what happens when invoked (external side effects possible, receipts written). Sufficient depth for a non-destructive, non-read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that packs endpoint, action, purpose, side effect, and permission requirements. It's compact and front-loaded with the core purpose. Minor point: 'Typed POST /v1/runs wrapper' is a bit dense for non-Hermes-savvy readers, but given the target audience of agents working with Hermes tools, this is acceptable. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with 100% schema coverage, an output schema, and an open-world hint annotation, the description adequately covers the essential context: what it does, its effects (receipts), and its permission gates. There's an output schema present so return values don't need elaboration. The description is complete enough for an agent to safely invoke this tool. Not perfect - it could mention the dry_run validation pathway more explicitly, but the schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the 7 parameters already having descriptive text in the schema. The description adds the prompt parameter's core purpose ('from a prompt'). Since the schema fully documents each parameter with defaults and descriptions, the description doesn't need to add much more; baseline 3 is appropriate given the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a typed POST /v1/runs wrapper that starts a Hermes agent run from a prompt. It names the specific API endpoint, the action (starts a run), the input (prompt), and mentions side effects (writing redacted receipts). This distinguishes it from siblings like hermes_api_runs_get or hermes_api_runs_stop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys it's for starting runs from a prompt, and requires api_call tier with live, model, agent-tool, and external-side-effect gates. It doesn't explicitly say when NOT to use it versus alternatives like hermes_api_jobs_create or hermes_api_chat_completions, but the run context plus the verbose gate requirements provide reasonable usage context. The dry_run param in schema allows validation without a live run, but this isn't highlighted as a usage strategy.
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?
Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds the offline/vendored nature (no network refresh) and the specific data surfaced (slugs, provenance, wrapper mapping), providing some value beyond annotations. However, it does not describe return format, ordering, or pagination behavior of the listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, dense sentence packs the full purpose and scope. It is front-loaded with the core action and enumerates the specific facets. Slightly verbose with the trailing 'without network refresh' but that qualifier is meaningful and earns its place. No wasted words or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a zero-parameter list tool with strong annotations (read-only, idempotent, non-destructive) and an output schema present, the description is complete for its purpose. It tells the agent what it lists (sections, provenance, wrapper mapping) and the offline constraint. The 'planned wrapper mapping' hint gives useful context about what the tool reports.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so schema coverage is 100% trivially. With no parameters to document, the description's job is minimal on this dimension. The description accurately describes what data is returned (section slugs, snapshot provenance, planned wrapper mapping), giving the agent a clear sense of the output even without parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('List bundled Hermes Kanban REST API documentation resources') and enumerates the facets exposed: section slugs, snapshot provenance, and planned wrapper mapping. It clearly distinguishes this tool from hermes_api_docs_list by scoping to 'bundled... without network refresh' (local snapshot vs possibly remote/refreshable docs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without network refresh' clearly signals this is the offline/bundled variant, and the sibling hermes_api_docs_list provides a natural contrast. It suggests when this is appropriate (reading bundled snapshot) versus alternatives, though it does not explicitly name the alternative tool or spell out when NOT to use it. Context is clear but exclusions are implicit rather than explicit.
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?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safe-read profile is covered. The description adds value beyond these by disclosing the 'writing redacted receipts' side effect—useful behavioral context that annotations don't capture. It's a read operation with a minor write side-effect disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single well-structured sentence that is technically informative ('Typed GET wrapper') and content-specific ('every board on disk with metadata, task counts, health, active board slug'), while flagging the receipt-writing behavior. No filler or redundancy across the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with 0 required params, full schema coverage, an output schema present, and strong annotations (readOnly, idempotent, non-destructive), this description covers the essentials: what's listed, what metadata is included, and the side-effect of redaction receipts. The return values need not be described since output schema exists. Minor gap: doesn't cover the write side-effect implications or any performance/filtering nuance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (include_counts, include_archived) are fully documented in the schema with clear descriptions and defaults. The description mentions 'task counts and health metadata' which maps to include_counts, and 'every board' implicitly touches the archived filtering, but doesn't add syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('Lists kanban boards') with clear scope: 'every board on disk with metadata, task counts, health, and the active board slug.' Distinguishes from siblings like hermes_kanban_board_get (single board) and hermes_kanban_config_get. The HTTP wrapper detail adds technical grounding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states what the listing includes, giving agents context on when to call it. However, it doesn't explicitly contrast with sibling tools like hermes_kanban_board_get or mention when to prefer one over the other, nor does it state exclusions or prerequisites.
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?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully declared. The description adds meaningful behavioral context beyond annotations by explicitly confirming 'without mutation or live API/model calls' — reassuring the agent this is purely local and side-effect-free. This reinforces and extends, rather than merely repeating, the annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence carrying high information density — it names the surfaces scanned and the safety guarantees. Zero filler words, no repetition of the title. Front-loaded with the action verb 'Detect'. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is handled externally. For a read-only detection tool with simple optional parameters, the description captures the full scope (all surfaces, no mutation, no live calls) without needing to enumerate details. Slightly under-complete only because it doesn't hint at what the return format distinguishes (e.g., found vs not-found, error behavior).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented. The description adds no parameter-specific detail beyond what the schema provides. However, the description's list of surfaces (CLI/home/profile/config/toolkit) implicitly maps to the home, profile, and toolkit_root params, giving mild additional context. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Detect') with a clear resource scope ('local Hermes CLI/home/profile/config/toolkit surfaces'). It explicitly enumerates what is covered, distinguishing this from siblings like hermes_status_overview and hermes_config_summary. The parenthetical clarifies it's about local surfaces, not remote/API state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use it: for detecting local installation surfaces. The 'without mutation or live API/model calls' phrasing implies this is a safe reconnaissance tool appropriate when exploring the local environment. It doesn't explicitly name alternatives or exclusions (e.g., 'use hermes_status_overview for runtime status'), but the scope is clear enough that an agent can differentiate it from the many API siblings.
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 annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description reinforces these by explicitly stating the tool lists without executing ('without executing the harness'). It adds the specific scope of what gets listed (files, dry-run markers, case counts, harness path state), which is useful behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that compactly lists what the tool does and explicitly notes what it does NOT do. Every element earns its place with zero filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description needn't explain return values. The tool is a simple read-only listing operation with good annotations (readOnlyHint, idempotentHint) and no required parameters, so the description covers the essential behavioral contract. The main minor gap is no hint about what the parameters are used for, but for a straightforward listing tool with optional parameters, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but all three parameters (home, profile, toolkit_root) appear to be optional configuration path/profile selectors that are common across the hermes_* family. The description doesn't add syntax or format details for these parameters beyond what the schema provides, which is a gap since no parameter-level help exists. However, no parameters are required, and their role as environment selectors is reasonably inferable from context, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination ('List configured Hermes eval suite files') and elaborates on what is included (dry-run markers, case counts, harness path state). It clearly distinguishes itself from sibling tools like hermes_eval_run and hermes_eval_start by explicitly noting it lists without executing the harness.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the 'when to use' by emphasizing this is an inspection-only operation that does NOT execute the harness, contrasting with evaluation-running siblings. It doesn't explicitly state when NOT to use it or name specific alternatives, but the context is clear enough for an agent to distinguish this read-only listing tool from eval-running tools.
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?
The description discloses several important behavioral traits beyond annotations: it requires a specific policy plus multiple gates (live/model/tool/external-side-effect), disables streaming in v0 (a significant behavior change from standard OpenAI semantics), and writes redacted request/result/response receipts. This is rich contextual disclosure that the annotations (which only mark openWorldHint=true) do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that packs substantial information (endpoint, compatibility, policy requirements, gates, streaming limitation, receipt behavior) into one well-structured sentence. Every clause earns its place and there is zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a comples tool with an output schema present, the description covers key operational concerns: policy requirements, gates, streaming behavior, and receipt redaction. It doesn't explain the return value structure, but the output schema exists to handle that. The main gap is lack of explicit usage guidance around when to prefer this over hermes_api_responses_create.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden for parameter semantics. The description notes streaming is disabled in v0, which meaningfully informs the 'stream' parameter. However, it does not detail the other parameters (model, messages, max_tokens, temperature) beyond what the schema already provides, though the schema itself is quite descriptive with $defs for message types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a chat completion via a Typed OpenAI-compatible POST /v1/chat/completions wrapper for mocked/local Hermes API endpoints. The verb+resource (create chat completion) is specific and distinguishes it from siblings like hermes_api_responses_create and hermes_kanban_* tools, though it could be clearer about what distinguishes it from hermes_api_responses_create since responses also involve completion-like calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it targets 'mocked/local Hermes API endpoints' which gives some context on when to use it, and notes it 'requires api_call policy plus live/model/tool/external-side-effect gates'. However, it does not explicitly name alternatives or state when NOT to use this versus other chat/completion tools.
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 annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value beyond these by specifying the exact guarantees: verifies branch, HEAD, cleanliness, and path containment, and does NO fetch, checkout, restart, or config writes. This reinforces and extends the annotation safety profile without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that compactly captures purpose, scope, and exclusions. Every clause earns its place. It could be slightly better structured (e.g., a second sentence separating what it verifies from what it avoids), but the current format is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters, an output schema, and strong safety annotations. The description covers the guard's verification dimensions and its non-mutating profile, which gives an agent enough to understand the commit/preflight role. It doesn't detail return value semantics, but the presence of an output schema shifts that burden away from the description. For a read-only guard with good annotations and output schema, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description meaningfully compensates by naming the four key verification dimensions (branch, HEAD, cleanliness, path containment). These map to expected_branch, expected_commit, require_clean_live, and source_checkout/live_checkout parameters. It doesn't explicitly document the 'home' or 'toolkit_root' params, but the 9-parameter schema with defaults and 0% coverage means the description's param naming carries real weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (guard/check) plus a clear resource (git/live-checkout) and enumerates exactly what it verifies: branch, HEAD, cleanliness, and path containment. It also explicitly negates what it does NOT do (no fetch, checkout, restart, or config writes), which sharply distinguishes it from sibling mutation tools like hermes_deploy_repair_apply or hermes_gateway_restart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it's a pre-deploy safety verification step, named 'guard'. It explicitly states what operations it avoids (no fetch, checkout, restart, config writes), which signals when-not-to-expect side effects. However, it does not explicitly name alternative guard/check tools for comparison or state when this tool should or should not be used relative to siblings.
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 key behavioral traits beyond annotations: it reports per-id outcomes without aborting siblings (failure isolation behavior), and writes 'redacted receipts' (security-conscious output redaction). With readOnlyHint=false and destructiveHint=false annotations present, the description's explicit non-aborting behavior and receipt-redaction add meaningful behavioral context beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that packs the endpoint, the operation scope, the patchable fields, the failure-isolation behavior, and the receipt-redaction detail without wasted words. It's compact but carries substantial meaning. Could benefit from a second sentence distinguishing edge cases, but as a one-liner it's efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 10 parameters with 100% schema coverage and an output schema present, which reduces the description's burden. The description covers the operation type, scope, and key behaviors. Given the complexity (bulk mutation with per-id outcomes), the description adequately frames the tool, though it could note which parameters are mutually exclusive (e.g., status vs archive vs completion).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so parameters are well-documented in the schema. The description adds the critical unifying semantics that all patches are applied to 'every id in the list' uniformly, and that status/assignee/priority/archive/completion are the patchable aspects. However, the description doesn't add parameter-level detail beyond what the schema already provides, so it hovers slightly above the baseline 3 rather than reaching 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a 'Typed POST /api/plugins/kanban/tasks/bulk wrapper' that applies patches 'to every id in the list', specifying the exact fields (status, assignee, priority, archive, or completion) and behaviors (per-id outcomes, no aborting siblings, redacted receipts). This is specific and distinct from the sibling hermes_kanban_task_update single-task tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes when to use this tool (bulk updates across multiple task ids) versus single-task alternatives. While it doesn't name specific sibling tools as alternatives, the bulk vs single distinction is evident, and the 'same patch to every id' semantics make the usage context 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds meaningful context beyond annotations by specifying the output granularity (sections, slugs, provenance, wrapper mapping) and the key behavioral trait that no network call occurs. It complements the annotations rather than repeating them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence that communicates purpose, resource, scope, and key behavior (offline snapshot access). Zero wasted words. Each element earned its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool with full annotation coverage and an output schema, the description is complete. It conveys the provenance and wrapper-mapping outputs, which is useful given no params. It doesn't describe return structure, but an output schema exists to carry that burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100%. Since there are no parameters to document, the not-applicable baseline of 4 applies. The description appropriately focuses on output characteristics since inputs don't exist to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'List' with specific resources: documentation resources, section slugs, snapshot provenance, and planned wrapper mapping. It distinguishes this from sibling tools like hermes_api_docs_read (reads docs) and hermes_kanban_api_docs_list (kanban-specific docs). The 'without network refresh' clarifies this is local snapshot data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The described scope (bundled/snapshot, no network refresh) clearly indicates when this tool is appropriate for inspecting local doc snapshots. However, it doesn't explicitly name alternative tools or state when NOT to use it (e.g., when you need live/refreshed docs), leaving some ambiguity for the agent.
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?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile thoroughly. The description adds valuable context about the offline nature ('bundled', 'without network, API, model, or tool calls') which explains performance and reliability characteristics. This adds genuine behavioral information beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence with zero wasted words. Every phrase earns its place: 'bundled' (offline), 'by slug or resource URI' (dual addressing), 'without network, API, model, or tool calls' (safety/performance). Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a read-only docs retrieval purpose, is accompanied by strong annotations (readOnly, idempotent, non-destructive), has an output schema, and 100% parameter schema coverage. The description adds the critical contextual nuance (offline behavior) beyond all structured fields. For a simple docs-reader tool, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (uri and section) are documented in the schema. The description adds context by showing example URI formats (hermes-docs://api-server/post-v1-chat-completions, hermes-docs://kanban-api/get-api-plugins-kanban-board) which demonstrates the URI pattern and links to the section param's source list. This exceeds the baseline-3 value for full-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Read one bundled Hermes Kanban API docs section by slug or hermes-docs://kanban-api/* resource URI without network, API, model, or tool calls.' It identifies the exact resource types (kanban-api docs) and the mechanism (slug or URI), distinguishing it from generic resource reads. It clearly differentiates this from siblings like hermes_api_docs_read by scoping to kanban-api.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the delivery mechanism (bundled, no network/API/model/tool calls), which implies offline/local usage context. It doesn't explicitly name alternatives like hermes_kanban_api_docs_list for discovery vs this for retrieval, but the schema's 'section' param referencing hermes_kanban_api_docs_list implies the workflow. Clear context but no explicit when-not-to-use or named exclusion.
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:

[![hermes-toolkit-mcp MCP server](https://glama.ai/mcp/servers/hermegeddon/hermes-toolkit-mcp/badges/card.svg)](https://glama.ai/mcp/servers/hermegeddon/hermes-toolkit-mcp)

Score Badge

Copy to your README.md:

[![hermes-toolkit-mcp MCP server](https://glama.ai/mcp/servers/hermegeddon/hermes-toolkit-mcp/badges/score.svg)](https://glama.ai/mcp/servers/hermegeddon/hermes-toolkit-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hermegeddon/hermes-toolkit-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server