List Hermes scheduled jobs

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.

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.

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.

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.

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.

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.