list_jobs

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

With no annotations provided, the description carries the full disclosure burden and does so well: it states the operation is read-only, not confirm-gated, purely in-memory, and not backed by an OctoBot route. It also discloses the return entry shape by referencing get_job_status minus sub_jobs.

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

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

The description is front-loaded with the core action and constraints, then delivers filters, safety semantics, and return-shape information in a compact structure. Every sentence earns its place and there is no filler or repetition.

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

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

For a simple read-only list tool with two optional parameters and no output schema, the description is complete: it covers scope, filtering values, optionality, side-effect behavior, and the return shape via a pointer to get_job_status. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 0%, but the description fully compensates by naming both parameters, listing their allowed values (state: queued/running/completed/failed/cancelled; kind: backtest/compare_strategies), and clarifying that each is optional and can be omitted independently. This adds meaning the bare schema lacks.

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 opening sentence names a specific action and resource: 'List jobs known to the in-memory job store, optionally filtered.' It also distinguishes itself from route-backed siblings by stating it maps to no OctoBot route and is purely an in-memory listing, so an agent can tell it apart from tools like get_job_status.

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 clearly explains filtering behavior: state and kind are optional, and omitting either or both disables that filter. It does not explicitly say when to prefer get_job_status over this tool, though mentioning get_job_status's shape implies the relationship; explicit alternative routing would make it a 5.

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