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

With no annotations, the description carries the behavioral transparency burden on its own. It discloses meaningful state-dependent behavior: queued jobs are cancelled, and running jobs receive SIGTERM via a worker signal poll in about 2 seconds. It does not cover idempotency, auth, or failure conditions, but the core cancellation semantics are clearly exposed.

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 dense sentence that front-loads the primary action and immediately clarifies state-dependent behavior. There is no filler, and the parenthetical adds crucial implementation detail without bloating the text.

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

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

The description is adequate for a simple cancellation operation, but gaps remain. It does not explain the response/acknowledgement behavior, what happens if the job is already in a terminal state, or how cancellation relates to the sibling jobd_preempt. Given that there is no output schema to compensate, these missing contextual details keep it below a 4.

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 50%, and the description adds little parameter-level meaning. 'Cancel a job' implicitly identifies job_id as the target job, but the description does not elaborate on job_id or reason. The reason parameter is already described in the schema, so the description itself contributes minimal semantic value beyond the schema.

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

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

The description states a specific verb and resource: 'Cancel a job'. It further clarifies the two main job states and what happens to each, which is more informative than a generic 'cancel job'. However, it does not explicitly distinguish itself from the sibling jobd_preempt, so it does not earn a 5.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as jobd_preempt or jobd_submit. It implies usage through its name and purpose, but the agent is left to infer the appropriate context, and no exclusions or alternative routing are provided.

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

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It does explain the semantic role of the stream and its diagnostic value, but it never explicitly states that this is a read-only operation, nor does it describe response shape, ordering, retention, or error behavior. The schema supplies some behavioral details (limit default and broker clamp), so this is not a complete gap, but the description alone is only minimally transparent.

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

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

The description is front-loaded with a strong purpose statement and every sentence contributes something: reason to use it, concrete illustrative examples, filter options, and a selection rule. It is slightly more expansive than necessary, but not bloated or repetitive.

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 filtered event stream with six optional parameters, the description covers the key selection context and when to use it, while the schema fills in defaults, enums, and the known event-type list. The lack of annotations and an output schema means returned payload shape is not fully specified, and the source mismatch is an inconsistency, but the tool is still reasonably invokable and well contextualized.

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

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

Schema coverage is 100%, so the baseline for parameter semantics is 3. However, the description's filter summary says source (broker|worker, while the schema enumerates four sources: broker, worker, hook, and mcp. This narrowing contradicts the schema and could lead an agent to ignore hook or mcp sources; it also omits limit from the summary. The description adds conceptual examples but actually detracts from parameter clarity.

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 names a specific resource—the broker's event stream—and states its distinguishing purpose: explaining WHY, not just what. It differentiates itself from /jobs and jobd_status with concrete examples (skipped 400 times, dependency cancelled, watchdog killed), so an agent can tell it apart from sibling tools without opening the schema.

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

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

The description gives an explicit when-to-use rule: 'Use when a job is not doing what you expect and jobd_status alone does not explain it.' It also contrasts with /jobs and mentions the alternative surface (jobd_status), providing an agent with a clear decision condition.

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

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

With no annotations, the description carries the load well: it discloses the default scope (active states only), that rows are compact summaries rather than full records, and directs to the sibling for detail. It omits pagination/truncation behavior (which lives in the schema) and any permissions or rate-limit notes, so it is strong but not exhaustive.

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?

Front-loaded with purpose and default scope, then filters, then return shape, then use cases — a sensible order with no filler. It is a dense run-on paragraph, which slightly hurts scanability but wastes no sentences.

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?

No output schema exists, and the description compensates by naming the returned row fields (job_id, project, state, host, exit_code, timestamps, duration_s) so the agent knows what it gets. Combined with default scope and sibling routing, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds intent-level meaning: the state filter is framed as the way to surface past runs, the finished_at window as the way to bracket history, and the default active set is restated for selection decisions. It complements rather than merely duplicates the schema.

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

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

States a specific verb+resource ('List jobs on the broker with per-state counts') and immediately distinguishes itself from the sibling by naming jobd_status for full records. An agent can tell exactly what this returns versus the other jobd_* tools without opening a schema.

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

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

Explicitly enumerates when to use it ('what is running / queued right now?', 'what failed overnight?', 'locate a job id you've lost') and names the alternative (jobd_status) for the full-record case. That is a clear when/when-not split with no inference needed.

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

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

With no annotations, the description carries the full burden. It discloses stream mechanics ('workers stream output to the broker's per-job log as it runs'), lifecycle support ('running AND finished'), and exact return semantics including tail_bytes default/max and truncation metadata. It does not explicitly state permissions, rate limits, or side-effect absence, but those are less critical for a tail/read operation.

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

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

Three dense sentences front-load the core action, follow with return format and lifecycle nuance, and end with concrete use cases. No filler, no repetition of schema fields that isn't functional.

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

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

Despite lacking an output schema, the description fully specifies the return shape (log_tail plus size_bytes/returned_bytes/truncated), the parameter semantics, and the supported job states. For a 2-parameter read tool, nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical guidance beyond the schema: 'Raise for context, lower for a quick liveness peek' for tail_bytes, and it reiterates the default and max. This is modest but genuine added semantic value.

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?

Specific verb+resource: 'Tail the captured stdout/stderr of a job.' The description clearly distinguishes from siblings like jobd_status by focusing on output logs, and clarifies it returns a tail of the log. It names the return payload and available metadata, making the tool's function unambiguous.

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

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

Explicit use cases are given: 'check progress mid-run, diagnose a failure's traceback, or grab a job's final output.' It also notes the tool works for 'running AND finished jobs,' which helps an agent decide when to call it. It does not name alternatives or when not to use it, so it stops shy of a 5.

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

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

With no annotations, this description carries the behavioral burden and does well: it discloses the worker side effect (SIGTERM with grace), the terminal state ('preempted'), and refusal conditions. There is a minor ambiguity between 'assigned' being preemptable and 'refused if not running', but overall the key behaviors are transparent.

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

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

The entire description is one dense sentence with no filler. It front-loads the core action and immediately follows with behavioral consequences and refusal criteria; every phrase earns its place.

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

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

For a single-parameter tool with no output schema, the description supplies the essential invocation context: what happens, what the final state is, and when the call fails. It does not describe the return payload, but given no output schema and simple side effects, the description is reasonably complete.

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

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

Schema coverage is 0%, but the sole parameter job_id is a simple integer whose meaning is obvious from the description. The description adds semantic constraints on which job_ids are valid (preemptible, running/assigned), which is useful context beyond the bare schema.

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

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

The description uses a specific verb ('Preempt') and a precise resource ('a running/assigned preemptible job'), and it names the distinguishing final state ('preempted'). It also implicitly differentiates from jobd_cancel by restricting preemption to preemptible jobs, so an agent can tell which sibling applies.

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

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

It clearly states when the tool is valid ('running/assigned preemptible job') and when it will be refused ('if not preemptible or not running'). It does not explicitly name an alternative such as jobd_cancel for non-preemptible jobs, which keeps it just short of a 5.

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

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

With no annotations present, the description carries the behavioral disclosure burden. It discloses the full return surface, the wait=true blocking behavior, and the timeout parameter, which is substantial context. It does not mention error behavior or side effects, but for a status tool this is reasonably complete.

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

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

The description is dense but every clause earns its place: return contents first, use cases second, wait behavior last. It avoids fluff and is well-structured for scanning.

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

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

Given the lack of an output schema, the description compensates by enumerating the returned fields and giving practical use cases. It could additionally explain how this tool differs from jobd_events or jobd_logs, and clarify whether a timeout returns partial data or errors, but it is largely sufficient.

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

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

Schema coverage is only 33%, but the description explains wait semantics directly ('block until terminal or wait_timeout_s') and makes job_id's role implicitly clear. The timeout clamp is already in the schema. This adds meaningful meaning beyond the bare schema.

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

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

The description precisely identifies the resource ('full JobInfo record for one job_id') and enumerates the returned fields, from state and exit_code to scheduling internals. It also distinguishes itself from sibling tools like jobd_list by emphasizing a single job and deep debugging detail.

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 states when to use the tool: for a quick state check and for debugging why a job routed, failed, or stalled. It does not explicitly name alternatives or exclusions, so it stops short of full guidance, but the usage context is unambiguous.

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

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

With no annotations, the description carries the burden, and it does disclose key behavioral traits: submission is asynchronous by default, wait=true switches to blocking, and wait_timeout_s is clamped to 270. It does not describe success responses or error conventions, though the side effect of submission is clear from the verb.

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

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

Two sentences with no filler: the primary behavior is front-loaded, and the timeout caveat is stated compactly. Nothing in the description repeats schema text unnecessarily.

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 10-parameter submission tool with no output schema, the description is relatively thin: it explains sync versus async but never states what a successful response contains (e.g., job_id or array_id), which the agent needs to hand off to jobd_status or jobd_logs. The rich parameter schema compensates for parameter details, but response expectations are left to inference.

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

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

Schema description coverage is 100%, so the parameter baseline is 3. The description adds a useful restatement of wait/wait_timeout_s semantics, but the remaining parameters are already fully documented in the schema, so no further compensation is needed.

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

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

The description uses a direct verb–resource pair ('Submit a job to the jobd broker') that clearly states the operation. It is set apart from the sibling tools, which are all post-submission queries or mutations such as jobd_status, jobd_logs, and jobd_cancel.

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

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

It gives an explicit usage default ('Default async') and the exact condition for the blocking alternative ('pass wait=true'), so an agent knows how to invoke it. It does not explicitly name sibling tools as alternatives, but the sibling list is dominated by post-submission operations, making the correct context fairly clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the 409 conflict behavior, the online/offline prerequisite, and the need to stop the worker or wait for the sweeper. This is substantive context beyond what the schema alone provides.

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

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

Two sentences, each earning its place: the first states the action, the second explains the key precondition and failure mode. 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 single-parameter, no-output-schema tool, the description covers the action, prerequisite, and error condition. It could optionally mention the success response shape or idempotency, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so the parameter 'host' is already documented as 'Worker host identifier.' The tool description adds no further meaning about the host parameter, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Remove') with a specific resource ('worker from the broker registry'), making the action unmistakable. It clearly differentiates from siblings like jobd_workers or jobd_submit without needing to compare schemas.

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

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

The description provides clear context: the worker must not be online, and the broker will return 409 otherwise. It also tells the caller how to proceed ('stops the worker process or waits for the heartbeat sweeper first'), though it does not explicitly mention alternative tools for inspecting workers before deletion.

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

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

With no annotations, the description handles transparency itself by labeling it a 'snapshot' (read-only point-in-time view) and naming all returned categories. It doesn't cover auth, staleness, or error behavior, but for a zero-parameter fleet status read the essential behavior is disclosed.

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 first sentence front-loads 'Fleet snapshot' and then packs the output contract into compact parenthetical lists; the second sentence adds concrete usage guidance. Every clause earns its place and there is no filler.

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

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

Despite lacking an output schema, the description enumerates the output fields, their possible values, and the health rollup states, and it supplies two relevant use cases. For a parameterless read-only fleet query, this is sufficient for an agent to invoke it correctly.

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

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

The tool takes zero parameters and schema coverage is 100%, so there are no parameter semantics to add. The description's field list primarily documents return content rather than inputs, which fits the baseline for parameterless tools.

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

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

The description opens with 'Fleet snapshot' and enumerates exactly what it returns: worker state, capacity fields, capability tags, slot usage, heartbeat, and health rollup. This makes the tool's resource and output clear, though it does not explicitly differentiate it from sibling tools like jobd_status or jobd_list.

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

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

It provides explicit use cases: use before submitting GPU work to check available capacity, or to diagnose why jobs aren't dispatched. It doesn't spell out when not to use it or name alternative tools, but the context is strong.

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