MDEngine

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the reserved-vs-available distinction, the two pricing modes and their caps, and the fact that packs are only present when the endpoint sells credit. It omits auth needs, rate limits, and error behavior.

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?

It is a single dense sentence where every clause carries information, and it front-loads the balance figures before pricing and packs. The heavy nested parentheticals make it harder to parse than it needs to be, but there is little wasted 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?

With no output schema, the description effectively serves as one, documenting balance, reserved, available, pricing modes, key id, and the packs array shape — a strong substitution. It is only slightly incomplete: the rate table structure is referenced but not described the way packs is.

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 schema has zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. All descriptive detail in the text is about return fields, not inputs.

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 enumerates exactly what the tool surfaces: balance_usd, reserved_usd/held_jobs, available_usd, pricing.mode, the rate table, the API key id, and packs. That specificity clearly separates it from the sibling job tools (submit_job, job_status, etc.), though it never states an explicit verb like 'Get' and opens with field names rather than a purpose statement.

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?

Usage is only implied: the note that available_usd is 'what a new submit can use' hints you call this before submitting, and the pack top-up instruction is a how-to for a follow-up action, not a when-to-use rule. There is no explicit guidance on when to call this versus capabilities or preflight_deck.

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?

Annotations mark this non-read-only and non-idempotent, so the key question is what actually happens — and the description answers it: 'Nothing is run or charged' and 'No key needed'. It also enumerates the response payload (request_id, tier, price band, gaps, next step, claim scope), which is meaningful behavioral context beyond the annotation flags.

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 short sentences, front-loaded with the key fact (no key needed) and the consequence (nothing is run or charged). The middle sentence is a dense list but every item earns its place given there is no output schema.

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, so the description usefully enumerates returned fields, and it states the non-committal nature of the call. It is close to complete for an agent deciding whether to invoke it; only the precise relationship to the job-execution siblings is unstated.

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 seven parameters are already documented in the schema; the description adds no parameter-level semantics such as format for grid or data_rules. Baseline 3 is appropriate when the schema carries the whole burden.

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 action and outcome: 'Sends a study request to a person and returns a request_id, the tier that fits, the price band...'. This is clearly a quoting/request step rather than a job execution, which distinguishes it from create_job/start_job/submit_job without naming them explicitly.

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?

'Call it after reading a guide' gives one sequencing hint and implicitly routes to the guide sibling. However it never states when to use this versus start_job or create_job, nor any preconditions tied to contact_email or customer_type. Usage 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.

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

The description aligns with annotations: it indicates destructive behavior ('pod is terminated') and idempotency is implied by 'not finished' (cancelling twice has no further effect). No contradictions with readOnlyHint or destructiveHint.

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 two sentences, direct and free of fluff. Every phrase adds value—clarifying the scope, the billing effect, and the termination outcome.

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 absence of an output schema, the description sufficiently explains what happens. It could benefit from mentioning possible outcomes (e.g., error on already-finished jobs), but in context with sibling tools like job_status, it is complete enough for an agent to invoke 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 single required parameter 'id' is fully described in the schema with a concrete example, and the description implies it identifies the job to cancel. Coverage is 100%, so no ambiguity remains.

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 explicitly states the tool cancels a job that is not finished, making the primary purpose unambiguous. The additional detail about billing and pod termination clarifies the action's implications.

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 implies the tool is for unfinished/running jobs, but does not explicitly contrast with sibling tools like start_job or submit_job. The condition 'not finished' serves as a clear usage hint, though not as explicit as naming alternatives.

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?

The annotations indicate read-only and non-destructive behavior, and the description adds valuable context about the output format (compact vs full table) and the meaning of the gpu flag, enhancing transparency beyond the annotations.

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 concise yet information-dense, covering the tool's purpose, output variations, and parameter usage in two sentences without redundancy.

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 absence of an output schema, the description sufficiently describes what will be returned (version, packages, styles) and the conditions for different outputs, making the tool's behavior clear for an agent.

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 schema descriptions for 'full' and 'runner' are complemented by detailed explanations in the description (e.g., 'runner=lammps&full=true returns the whole style table'), which clarifies the practical effect of each parameter.

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?

Clearly states it returns a capability manifest (LAMMPS version, packages, styles) and distinguishes itself from preflight_deck. The specific mention of 'capability manifest' and the breakdown of content makes its purpose unambiguous.

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

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

Explicitly directs users to use preflight_deck for checking a specific deck, providing a clear alternative. It also explains parameter effects (default vs full output) and the runner parameter, giving concrete usage guidance.

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?

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false) plus openWorld, so the bar is lower, yet the description adds real context: it reserves rather than launches, what the upload artifact must be (.tar.gz, <=2 GB, relative paths), and the exact follow-up call. It does not cover auth requirements or what happens to abandoned reserved 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?

Two sentences, zero filler. The role in the workflow is front-loaded, followed immediately by the concrete upload contract and the required next step.

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?

With no output schema, the description carries the return value (presigned upload_url) and the full lifecycle an agent needs: validate, reserve, upload, then call start_job. For an 8-parameter creation tool, 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 coverage is 100%, so the baseline is 3 and the schema already documents all eight parameters. The description still adds meaning by clarifying that the deck's input script is referenced with relative paths and lives at `input` inside the uploaded archive, which disambiguates the required parameter in the context of the upload step.

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?

Names a specific verb+resource (create_job / reserves a job id) and states its exact position in the pipeline: step 1 of a two-step path. It is clearly distinguishable from start_job and submit_job because it says this one only validates and reserves the id, returning an upload_url rather than launching work.

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 ties itself to 'big decks' and tells the agent the next call (start_job), which is strong sequencing guidance. The qualifier 'for big decks' implies the small-deck alternative (submit_job) without naming it, so the exclusion is only suggested rather than stated.

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?

Annotations already mark the tool destructive and not read-only, and the description adds concrete consequences: it deletes deck and results tarballs, retains metadata and billing records, and ends download availability. This goes beyond the generic flags and gives an agent accurate side-effect expectations.

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 front-load the main action and timing, followed by the retention consequence. There is no filler, title repetition, or schema duplication.

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 one-parameter destructive action with no output schema, the description covers what is deleted, when, what is kept, and what becomes impossible after call. The control, timing, irreversible consequence, and total job data target are enough for correct invocation.

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% and the single id parameter is already described with an example and required marker, so the baseline applies. The description's 'finished job' condition adds some targeting nuance, but no meaning beyond the schema is required. No extra parameter semantics gap exists.

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?

Description names the exact action ('delete its deck and results tarballs') and the resource (files of a finished job), immediately distinguishing it from siblings like cancel_job or job_results. It also demarcates what is not deleted, making the tool's scope 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?

The description gives a clear trigger—call this on finished jobs to delete files immediately instead of waiting for the 30-day purge—and states a functional consequence. It does not explicitly name alternatives such as job_results for downloading afterward or cancel_job for unfinished jobs, so it stops short of full when-not-to-use guidance.

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?

Annotations already establish readOnly/idempotent/non-destructive/openWorld, but the description adds real value beyond them: it discloses that no API key is required and describes what each mode returns (one-line list plus start page and key instructions; full guide with inputs, execution, outputs and cost). It stops short of noting any limits, but with annotations covering the safety profile this is solid.

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 parallel sentences, each mapping to one parameter state, with the most important fact ('No key needed') front-loaded. No filler; every clause carries behavioral or routing information.

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?

Zero required parameters, no output schema, read-only. The description compensates by describing the return payload for each of the three modes, so an agent knows what to expect from every invocation shape without needing an output schema.

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 would be 3, but the description goes further by explaining the conditional interaction between the two parameters (what happens with neither, one, or the other) and by enumerating the disappearance of customer_type to trigger list mode. That is meaningfully more than the schema's terse per-parameter notes.

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 the resource (guides) and spells out three distinct behaviors selected by parameters: list mode, full-guide mode, and template mode. This is specific enough that an agent can distinguish it from siblings like 'capabilities' or 'account' 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?

It gives clear conditional usage: omit customer_type for the list, supply it for the full guide, use template for script text, and notes no key is needed. It does not compare against sibling tools that might also serve as entry points (e.g. 'capabilities'), so the routing guidance is good but not exhaustive.

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?

Annotations already communicate read-only, idempotent, and non-destructive behavior. The description adds useful behavioral details: it reflects a running pod's recent output and has a 30-second heartbeat freshness, which helps set expectations about data recency.

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 two short sentences with the core purpose stated first and supplementary context second. There is no redundant or extraneous wording.

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 log-tail tool, the description covers what is returned, how fresh it is, and where to find the full log. It does not specify output formatting, but the tool's simplicity and annotations make the description sufficient for correct use.

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 schema fully documents the single required id parameter with an example, so the baseline is met. The description does not add extra parameter-specific semantics, but none are needed given the simple and obvious id field.

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 identifies the tool as returning the last <=20 thermo/log lines from a running pod, which is a specific and recognizable retrieval action. It also distinguishes itself from the full log by noting that the full log.lammps is in the results tarball.

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 useful context by mentioning the 30-second heartbeat and that the full log is in the results tarball, but it does not explicitly name sibling tools like job_results or state when to prefer this tail view over the full log. The guidance is implicit rather than direct.

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?

Adds important behavioral details: URL validity ~7 days and results deletion after 30 days, complementing the readOnly and non-destructive annotations.

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 concise sentences that front-load the purpose and key constraints without redundancy.

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?

Complete for a simple read-only tool: states purpose, conditions, and important time-bound behavior. No output schema exists to require additional detail.

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 fully covers the single 'id' parameter; the description does not add extra meaning beyond the schema's own description.

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?

Clearly states the tool returns a presigned download URL for job results, distinguishing it from job_log, job_status, and delete_results.

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?

Provides condition 'for a done/failed job' but does not explicitly mention alternatives or when not to use, though the context is 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value by defining the post-run verdict semantics (clean vs warnings, with the specific log conditions — QEq CG failures, lost atoms, fix halt, missing end_marker — that trigger warnings), which no annotation conveys.

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?

A single dense sentence that front-loads the state enum and then the returned fields; there is no filler. It is listy rather than prose, but every clause carries information.

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?

With no output schema, the description must describe the return payload, and it does so fairly thoroughly, including the verdict logic. What is missing is any indication of staleness/live-fetch behavior or whether failed/cancelled runs omit fields such as cost or exit code.

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?

One required parameter at 100% schema description coverage, so the schema already documents the job id format. The description adds no additional meaning about `id` and is not expected to at this coverage level, giving the baseline 3.

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 enumerates exactly what the tool returns (state, GPU, rate, billed seconds, cost, exit code, error, thermo lines, verdict), which makes the read-only status-fetch purpose unambiguous. It does not, however, name job_log or job_results even though it overlaps with them on thermo lines and results, so the agent must infer the boundary.

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?

There is no statement of when to call this versus job_log, job_results, or list_jobs, and no note about polling or freshness. The agent gets the payload contents but no routing guidance.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds behavioral details beyond annotations: the ordering ('newest first') and the effect of full=true (switching from compact rows to complete status object). 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.

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

The description is a single, compact sentence that front-loads the core purpose (jobs of this API key, newest first) and then adds the output format detail. No wasted words, and the key information is immediately accessible.

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 read-only listing tool with no output schema, the description provides the essential return fields (id, state, label, created, finished, gpu, cost_usd, error) and the full option. It does not mention pagination beyond the limit parameter (which is in the schema) or error behavior, but given the simplicity and annotation coverage, it 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 description coverage is 100%, so both 'full' and 'limit' are already documented. The description adds context for 'full' ('unless full=true' implying a switch to complete status objects), which goes slightly beyond the schema. However, it does not add any meaning for 'limit', so it only partially enhances parameter understanding. Baseline 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 states a specific verb-resource pair: 'Jobs of this API key' clearly indicates a listing operation scoped to the caller's API key, with a defined ordering ('newest first'). It also distinguishes itself from siblings like job_status (single job) and job_results (specific results) by the scope and output format.

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 implies when to use it—listing all jobs for the API key—and the output format (compact vs full). However, it does not explicitly state alternatives or exclusions, such as 'for a single job, use job_status', leaving the routing to siblings implicit. Given the clear context and sibling names, this is adequate but not fully explicit.

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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive behavior, and the description adds valuable behavioral context: the run would exit at startup if styles are missing on every image, package-dependent decks automatically route to lammps-full, and nothing is billed. This goes well beyond the annotation hints and gives the agent a concrete model of what happens.

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 information-dense sentence with a front-loaded purpose ('Dry run of the check submit_job performs') and a clear list of outputs. Every clause earns its place, including the safety guarantee and routing behavior, with no filler or repetition of the title.

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?

With no output schema, the description serves as the output contract by enumerating the four decision-relevant results: missing styles, CPU-only styles, GPU usage, and the runner image. It also covers side effects and routing implications, making it complete for an agent to decide when to call the tool and what to do with the result.

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%, and both parameters are already well documented: files is the deck contents map and input is the relative path to the input script. The description adds context about what the deck is used for but does not add new parameter-level syntax or format details, so the baseline 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 names a specific operation—a preflight dry run on a deck—and enumerates the exact questions it answers: missing styles, CPU-only styles, GPU usage, and routed runner image. It also distinguishes itself from submit_job by explicitly labeling itself as the dry run of the check submit_job performs.

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 title and phrase 'before spending' plus 'Nothing is created or billed' clearly establish when to use this tool: as a safe precursor to submit_job. It does not explicitly list exclusions or name alternatives, but the comparison to submit_job and the cost-safety framing make the intended usage 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?

The description discloses important behavioral consequences beyond what annotations provide: it launches a GPU pod and starts billing when the pod reports running. This adds context about side effects and cost, which is valuable for an agent deciding whether to invoke it. It does not contradict the annotations (readOnlyHint=false, non-idempotent, non-destructive).

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 two sentences, front-loaded with the action and sequence step, and includes only essential details (precondition, pod launch, billing). There is no fluff or redundancy, making it highly efficient for an agent to parse quickly.

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 covers the key prerequisites (uploaded tarball), the action, and side effects (pod launch, billing). It lacks explicit mention of what happens on failure or how to check status, but the sibling tools (job_status, job_log) and the non-idempotent annotation cover those aspects. For a simple one-parameter tool, this is fairly 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?

The input schema already provides full coverage for the single 'id' parameter with an example format. The description does not add any extra meaning about the parameter itself, so it relies on the schema. Baseline of 3 is appropriate since schema coverage is 100%.

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 the action (queue a job) and the resource (an uploaded job's deck tarball). It positions it as 'Step 2', which helps differentiate it from siblings like create_job or submit_job, but it does not explicitly name those alternatives. The purpose is specific enough to avoid confusion with cancel_job or delete_results.

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 implies a precondition (deck tarball already uploaded) and a sequence ('Step 2'), which gives some usage context. However, it does not explicitly state when not to use this tool or point to alternatives like submit_job for creating a new job. The guidance is implicit rather than explicit, so it is adequate but not strong.

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?

Annotations declare it is a non-read-only, non-idempotent, open-world write, and the description adds substantive behavior beyond them: billing starts at the first heartbeat (state running) and stops at done/failed/cancelled, and the deck runs on an isolated GPU pod. These are exactly the cost/lifecycle facts an agent needs before submitting.

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 sentences, front-loaded with the one-call composite behavior, then the size threshold and fallback path, then billing lifecycle. No redundant restatement of the title or schema.

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?

With no output schema, the description still covers the workflow, the size constraint, the escape hatch, billing boundaries, and execution isolation; all nine parameters carry schema descriptions. Nothing needed to invoke this tool 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 coverage is 100%, so baseline is 3, and the description adds real value by clarifying files must be supplied INLINE as {relative_path: text} with an 8 MB ceiling that is not encoded anywhere in the schema. It stops short of explaining gpu/launch/end_marker semantics, which the schema already handles well.

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 first sentence names a specific verb set and resource (create a hosted GPU job, upload the inline deck, queue it) and the title/description make clear it is a one-call composite. It explicitly distinguishes itself from the create_job + PUT + start_job path used by siblings, so an agent can route correctly without opening 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?

Gives an explicit threshold for choosing this tool (inline total <= 8 MB) and names the exact alternative workflow with its three sibling tools when the deck is larger. This is textbook when-to-use / when-not-to-use guidance.

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