MDEngine

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds what data is returned but does not contradict the annotations, so it provides some additional context.

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, concise, and informative sentence that lists the returned data without any fluff or 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?

With no parameters and no output schema, the description adequately specifies what the tool returns (balance, rate table, key ID), making it complete for a simple account query tool.

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 has no parameters and schema coverage is 100%, so the baseline score of 4 applies. The description does not need to add parameter meaning.

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 clearly states the tool returns account balance in USD, per-GPU hourly rate table, and API key ID, which is a specific resource and differentiates from all job-related sibling tools.

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 does not explicitly state when to use this tool vs. alternatives, though the sibling context implies it is for account information. No direct usage guidance is 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?

Annotations already mark destructive and idempotent behavior, and the description adds concrete details about billing cutoff and pod termination. It does not fully explain behavior when the job is already finished, but the annotation coverage lowers the burden.

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 unnecessary information. It front-loads the primary purpose and then gives relevant side effects.

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 main action, applicable state, and side effects, which is sufficient for this simple tool. It omits potential error/return behavior, but given no output schema and low complexity, this is not a significant gap.

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 already fully describes the single required parameter 'id' with an example. The description adds no additional parameter-specific meaning, so the 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 clearly states the tool cancels a job that is not finished, with a specific verb and object. It differentiates from sibling tools like create_job, start_job, and submit_job by focusing on cancellation.

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 specifies the condition 'not finished' and explains billing and pod termination, giving practical guidance. It could be more explicit about using it for running or queued jobs versus completed ones, but the intent 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?

Beyond annotations (readOnlyHint=false, idempotentHint=false), the description adds valuable context: the upload step, the tar.gz format, and the size limit. It also implies a reservation side effect ('reserves a job id'). This is meaningful behavioral disclosure not present in 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 two sentences, front-loaded with the core purpose and immediately followed by the next step. Every word contributes; there is no filler or 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 tool's complexity (7 params, no output schema), the description covers the essential flow: validation, job id reservation, upload URL, and the follow-up call to start_job. It does not explicitly state the full response payload (e.g., whether job_id is returned alongside upload_url), but the mention of 'reserves a job id' implies it, and the lack of an output schema makes this a minor gap.

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. The description adds value by clarifying the 'input' parameter ('input at `input`') and the deck format constraints (.tar.gz <= 2 GB), which enriches understanding beyond the schema's per-parameter descriptions.

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 action ('validates the spec, reserves a job id, returns a presigned upload_url') and explicitly positions it as 'Step 1 of the two-step path for big decks'. This clearly distinguishes it from siblings like submit_job and start_job, leaving no ambiguity about its role.

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 explicitly states the tool is for big decks and that it's the first step, then instructs to 'PUT the deck... to upload_url, then call start_job'. This gives clear when-to-use and follow-up guidance, though it doesn't explicitly name the alternative for small decks (submit_job) 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.

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

The description goes beyond the read-only annotation by specifying the log line limit and the heartbeat interval. However, it does not explain edge cases such as behavior when the job ID is invalid or when no logs are available, and it does not mention any rate limits or error conditions.

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 directly conveys the essential information without any redundancy or unnecessary detail. It is well-structured and easy to parse.

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 simplicity of the tool (one parameter, no output schema), the description is largely sufficient. It conveys what data is returned (log lines) and the constraints (max 20 lines, 30s heartbeat). It could be slightly improved by hinting at the output format, but the current level is adequate for this straightforward operation.

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 already provides a description for the 'id' parameter with an example, achieving full coverage. The tool description adds no additional semantic meaning about the parameter, such as required format or constraints, so the baseline score of 3 applies.

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 tool's function: retrieving the last up to 20 thermo/log lines from a running pod. It includes a specific detail about the 30-second heartbeat, which distinguishes it from sibling tools like job_status or job_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 does not provide explicit guidance on when to use this tool versus alternatives. It lacks any mention of typical use cases (e.g., debugging, monitoring) or situations where other tools like job_results would be preferable.

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?

Discloses URL validity (~7 days) and results deletion (30 days), adding important temporal constraints beyond the read-only annotations. Does not mention error conditions (e.g., job still running) but scope is implied.

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?

Concise two-sentence description with clear structure: conditions, what is returned, and retention policy. No unnecessary words.

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 there is no output schema, the description sufficiently explains what the output contains (tarball with work/, log.lammps, exitcode). Does not specify response format but that is standard for such endpoints. Minor gap: behavior for non-terminal jobs.

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 only parameter id is fully described in the input schema (100% coverage), so the tool description adds no additional parameter semantics. Baseline score applies.

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 provides a presigned download URL for results of a done/failed job, distinguishing it from siblings like job_log or 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?

Implies usage when a job is done or failed, and the description of the tarball contents helps determine when results are needed. Does not explicitly name alternatives but context makes it 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 annotations already confirm read-only, idempotent, and non-destructive behavior. The description adds context about the returned fields (cost, error, thermo lines) but does not discuss potential side effects, error handling, or rate limits, though the annotations cover the main safety aspects.

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 enumerating the returned fields. It is direct and contains no redundant wording, making it highly efficient for an agent to parse.

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 there is no output schema, the description adequately lists the information returned (state, GPU, rate, billed seconds, cost, exit code, error, thermo lines). It does not specify formatting or error responses, but for a simple status tool, this level of detail is sufficient for an agent to know what to expect.

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 only parameter (id) has full schema description coverage with an example format. The tool description does not add further semantic detail about the id parameter, but the schema already provides sufficient meaning, 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 clearly indicates the tool returns job status information by listing the fields it provides (state, GPU, rate, etc.). While it lacks an explicit verb like 'get' or 'retrieve', the title 'Job status' and the field list make the 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?

No guidance is given on when to use this tool versus alternatives like job_log or job_results. Given the sibling tools, a brief note on how this differs (e.g., 'use for current status, not historical logs') would clarify selection.

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, idempotent, and non-destructive behavior. The description adds no conflicting information and aligns with these annotations. No additional side-effect disclosure is needed.

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 focused sentence, providing the essential information without unnecessary elaboration.

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 straightforward resource (jobs), the clear schema, and the annotations, the description is complete. It does not require additional context about return formats or side effects, as none are specified and the scope is simple.

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 parameter 'limit' is fully described in the schema with its range and default value. The description does not need to add more, as the schema covers it completely.

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 ('List jobs') and specifies the scope ('of this API key') and ordering ('newest first'). It distinguishes this tool from siblings like job_status or job_results by implying a general listing rather than a single job's details.

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 usage for retrieving all jobs for the API key, which is distinct from sibling tools like job_status (likely for a single job) or submit_job (for creation). While not explicit, the phrase 'Jobs of this API key' makes the intended use clear enough.

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?

Beyond the annotations, the description discloses meaningful behavioral consequences: a GPU pod is launched and billing starts when the pod reports running. This adds real decision-relevant context for an action that is not read-only and not idempotent.

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?

One tight sentence front-loads the workflow step and prerequisite, then adds the essential side effects. Every clause earns its place with 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.

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

For a single-parameter tool whose schema fully covers the input, the description provides the key operational context: valid precondition, what launching means, and the billing trigger. The absence of an output schema is mitigated by the low complexity and the availability of sibling tools like job_status for follow-up.

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 already documents the single id parameter at 100% coverage. The description adds no additional parameter-level detail, so the baseline score of 3 is appropriate; the schema carries the 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 ('queue a job') and resource ('whose deck tarball has been uploaded'), with concrete consequences (GPU pod launched, billing starts). It positions itself as Step 2, which helps distinguish it from earlier upload/creation steps, though it does not name sibling alternatives 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?

The phrase 'Step 2' and the prerequisite 'deck tarball has been uploaded' give clear context for when this tool should be called. It does not explicitly state when not to use it or name alternatives like submit_job, so it stops short of full 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 indicate non-read-only, non-idempotent behavior, and the description adds billing-start/stop semantics and the hard wall-cap failure behavior. It does not contradict annotations and gives useful side-effect context beyond the structured hints.

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 stays on-topic, packing purpose, usage boundaries, billing behavior, and safety guidance into one paragraph. Slightly long, but every clause carries meaningful 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?

The description covers the action and side effects well, but with no output schema it does not state what the call returns (e.g., job ID or status). This leaves a moderate gap for an agent relying on the description alone.

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 descriptions cover all parameters, and the description adds important nuance such as estimate_s being only for the balance pre-check and wall_limit_s being a hard billable cap. This goes beyond the schema's baseline explanations.

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 a single call creates a hosted GPU job, uploads the inline deck, and queues it. It explicitly contrasts with create_job/start_job for larger decks, making the tool's unique role unmistakable.

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 when-to-use guidance: inline decks up to 8 MB, and larger decks should use create_job, PUT to upload_url, then start_job. It also explains billing lifecycle and cautions to only submit read content, giving practical usage guardrails.

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