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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds substantial behavior beyond that: state-changing and billable, no cost preview or published rate, 402 means insufficient credits, labels are additive and never overwritten, a dataset version snapshot is taken before every run, and billing settles at run time so stop does not refund.

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?

Dense but front-loaded with the core action and reference formats before cost/lifecycle details. Every sentence carries load given the tool's complexity, though the single undivided paragraph is heavier than ideal.

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 an 8-parameter billable mutation with no output schema, the description covers cost gating, billing timing, snapshot/undo path via dataset_version_restore, additive labelling semantics, and polling/cancellation siblings. An agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining that only explicitly set optional params are transmitted and the rest fall to server defaults, that class_mapping passes through with no length check, and that there is deliberately no imgsz parameter. These are semantics the schema alone does not convey.

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 ("Start an auto-annotation run on a dataset") and enumerates the accepted reference formats for both dataset and model. It is clearly distinguished from siblings auto_annotate_status and auto_annotate_stop, which it names.

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 when-to-use and how-to-prepare: confirm_cost=true is mandatory, cost magnitude is gauged via datasets_get, class_mapping is the remedy for taxonomy mismatch, and status/stop are named for polling and cancellation. Nothing is left to inference.

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 annotations already declaring readOnlyHint=true and destructiveHint=false, the description goes well beyond them by disclosing the return semantics: both-null means never run, activeJob carries in-flight progress, lastRun carries failed/stopped booleans plus results or an error. This is exactly the behavioral context an agent needs since no output schema exists.

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-loaded with the purpose and addressing, followed by return semantics. Every clause carries information, though the enumeration of null cases is slightly dense.

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 read tool, the description fully covers both how to address the dataset and what the return values mean, including edge cases. Nothing an agent needs to interpret the response 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?

Only one parameter with 100% schema description coverage, so the baseline is 4. The description restates the slug / owner-slug / ul:// URI forms already documented in the schema, adding no new syntax beyond it.

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 (Get) and resource (auto-annotation run's status) with the addressing forms for the dataset. It is clearly distinguishable from siblings auto_annotate_start/auto_annotate_stop, which mutate run state, while this only reads it.

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 polling status after starting a run and gives the accepted dataset reference forms, but it never explicitly says when to call this versus auto_annotate_start/stop or when the result is meaningful. Usage is left to inference.

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?

Goes well beyond annotations by disclosing the status-precheck/refusal behavior, the exact returned action verbs (cancelled/dismissed/none surfaced verbatim), the gating model ('ships ungated'), and two side-effect clarifications (undismissed terminal run doesn't block next start; dismissal moves no money). Annotations only flag destructive/readOnly, so this adds substantial 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?

Purpose and input forms are front-loaded in the first sentence, and each subsequent sentence adds a distinct behavioral fact (precheck, return verbs, gating, side effects). No filler or redundant restatement of the name.

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, yet the description explains the returned action vocabulary and the refusal path, plus side-effect and gating behavior. For a single-param mutation tool this leaves nothing an agent needs 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 single 'dataset' parameter is already fully documented. The description repeats the same slug/owner-slug/URI forms without adding syntax or format detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (stop/dismiss) and resource (dataset's auto-annotation run), and enumerates the three accepted ref forms. An agent can distinguish it from auto_annotate_start and auto_annotate_status from the description alone.

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 clear preconditions: it reads status first and refuses without calling the endpoint when no run is active, and it distinguishes mid-flight cancellation from clearing a terminal run's summary. It does not explicitly route the agent to a sibling (e.g. auto_annotate_status) for checking first, so it stops short of full when-to-use/when-not 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 only declare readOnlyHint/destructiveHint safety, so the description adds real value by disclosing the default shape of the response (histogram/heatmap groups stripped, omitted groups named in the summary) and the exact opt-in that restores them. It stops short of describing structure of the per-class counts themselves, and much of the payload-shaping detail also appears in the include_histograms schema description.

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 dense sentences, with the core purpose and accepted reference forms front-loaded and the default/opt-in behavior following. The parenthetical enumeration of histogram and heatmap groups duplicates the schema description of include_histograms, which is minor waste.

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 burden of explaining the return content, and it does so reasonably: it states the tool returns per-class annotation counts and describes the default trimming and the summary note about omitted groups. It does not describe the shape of the per-class count entries themselves, which leaves a small 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 description coverage is 100%, so both parameters are already documented, including the accepted ref formats and the histogram enumeration. The description restates the same accepted reference forms and the same omitted-group list, adding little semantic value beyond the schema; the baseline 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?

States a specific verb+resource ('per-class annotation counts for a dataset') and names all three accepted reference forms (slug, owner/slug, ul:// URI). This is clearly distinguishable from nearby siblings like datasets_get or explore_datasets, which do not return per-class statistics.

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 clear context for the one meaningful choice: by default the bulky groups are omitted, and 'pass include_histograms: true to get the full payload unmodified.' That tells the agent when to use the non-default path, but names no alternative sibling tool and gives no explicit 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 readOnlyHint=true and destructiveHint=false. The description adds a real behavioral trait beyond them — the link is 'time-limited' — which matters for callers, though it does not say how long the link lasts or what happens if it expires.

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 dense sentence, front-loaded with the verb and result, then the acceptable inputs and the latest-vs-frozen distinction. Slightly long in listing three ref formats, but no wasted 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?

No output schema exists, and the description compensates by stating the return is a download link. Both parameters are documented, and the version-selection behavior is covered; only link lifetime and failure modes are left unstated, which is a minor gap for a read-only lookup.

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 slightly exceeds the schema: it restates the accepted dataset ref formats and clarifies that omitting version yields the latest export versus a frozen version, adding semantics beyond 'Saved version number.'

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 and resource — retrieving a time-limited export download link for a dataset — plus the accepted reference formats. It reads clearly against siblings like export_create/exports_list, though it never explicitly names an alternative to disambiguate.

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 implied: the agent understands this fetches a link rather than creating or listing exports. It adds a selection condition ('latest export or one frozen version') but gives no explicit when-to-use vs export_status/exports_list guidance and no prerequisites.

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 and destructiveHint=false, so the safety profile is covered. The description adds the accepted identifier forms, but this duplicates what the schema's dataset parameter already says. Pagination behavior (limit/offset) and return shape are undisclosed.

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 front-loaded sentence with the action and resource leading. No waste, though its brevity comes partly from omitting genuinely useful detail rather than pure economy.

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 an 8-parameter list tool with no output schema, the description covers the basics but adds nothing about pagination limits, how filters combine, or result ordering. Schema carries the parameter burden, but the description is thinner than the tool's complexity warrants.

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 schema fully documents all 8 parameters including the non-obvious empty-array semantics of classIds. The description's 'optional filtering' adds no syntax or meaning beyond the schema, so the baseline 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?

States a specific verb (List) and resource (images in a dataset), and enumerates the accepted dataset reference forms (slug, owner/slug, ul:// URI). This is clear enough to distinguish from datasets_list or datasets_get, though it never names a sibling 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 'with optional filtering' implies you can narrow results, but there is no when-to-use, when-not-to-use, or alternative routing guidance. The agent must infer the tool's place among 40+ siblings on its own.

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 and open-world profile, so the bar is lower, and the description adds real context: the job is asynchronous (queued job id), conflictPolicy defaults to skip while the platform default is undocumented, and it returns the dataset's current ingest status. It stops short of describing auth requirements or failure modes.

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 tight sentences, front-loaded with the action and reference formats, then the default and the follow-up hint. No wasted text, though the parenthetical about the undocumented default is slightly verbose.

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 mutation tool with no output schema, the description usefully explains what comes back (queued job id plus current ingest status) and points to the follow-up tool, covering the async lifecycle. It does not address permissions or what happens on ingest failure, so it is not fully 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 the baseline is 3. The description mostly restates what the schema already documents (dataset ref formats, conflictPolicy default of skip); the only added nuance is that the platform default is undocumented, which is marginal.

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 (start ingest job), the resource (remote URL ingest for a dataset), and the accepted dataset reference formats. This clearly distinguishes it from the local-upload siblings (dataset_upload_file/folder/video) and from datasets_get.

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?

Names the follow-up tool explicitly ('use datasets_get to follow up'), which gives the agent a clear next step. It does not, however, state when to prefer this over the local-upload siblings, leaving that distinction to inference from the 'remote URL' wording.

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=false and destructiveHint=false, so the safety profile is partly covered. The description adds a genuinely non-obvious behavioral trait: the tool defaults to private visibility even though the underlying platform defaults to public when omitted, which is exactly the kind of gotcha that changes how an agent calls it.

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 tightly written sentences with zero filler, and the important default-behavior caveat is front-loaded after the core purpose.

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 mutation tool with no output schema, complete parameter docs, and annotations covering the safety profile, the description supplies the one piece of behavior an agent would otherwise get wrong (the visibility default). It stops short of noting idempotency or permissions, but the annotation already flags non-idempotency.

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 schema already documents all seven parameters including visibility and the private/public values. The description's visibility-default note reinforces rather than extends the schema, 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?

States a specific verb and resource ('Create a dataset in your Ultralytics workspace'), which clearly distinguishes it from siblings like datasets_list, datasets_get, and datasets_delete. It does not explicitly name a sibling it should be chosen over, but the create semantics are 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?

There is no explicit when-to-use or when-not-to-use guidance and no alternatives are named. The create verb implies its purpose, but for a workspace that also has dataset_version_create and dataset_ingest, the description gives no help in choosing among them.

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=false and destructiveHint=true, so the safety profile is covered; the description goes further and discloses cascade scope (images and annotations move to trash) and that models are unaffected. The only weakness is the vague 'bounded window' for restorability, which never states an actual duration.

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 operation and accepted identifiers, followed by the two consequence facts. Nothing is padded and each sentence carries distinct 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?

No output schema exists, so the description must carry the outcome story, and it does cover cascade and restorability. It omits permission requirements, behavior on invalid/unknown slugs, and the actual permanence period, which a destructive single-parameter tool would ideally state.

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 the single 'dataset' parameter is fully documented in the schema, including all three accepted formats. The description merely repeats that same enumeration, adding no syntax, validation, or edge-case meaning 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?

States a specific verb (Delete) and resource (dataset), plus the three accepted reference formats, so an agent can immediately distinguish it from datasets_get, datasets_list, and datasets_create. The cascade sentence further pins down the exact operation.

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 implied by the destructive verb, but there is no explicit when-to-use/when-not-to-use guidance and no routing to alternatives such as projects_delete or models_delete. The note that models trained on the dataset are not deleted is a useful consequence hint but is not framed as selection 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 and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no note on failure behavior for unresolvable slugs, no visibility/permission constraints, and no indication of what the returned detail includes.

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 tight sentence with the action front-loaded and zero filler. Every clause (verb, resource, accepted identifier forms) 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?

For a single-parameter, read-only getter with full schema coverage and no output schema, the description plus annotations give an agent enough to call it correctly. It stops short of five because it never distinguishes itself from datasets_list/explore_datasets in the description itself.

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 the description restates the exact same accepted formats (slug, owner/slug, ul:// URI) verbatim, adding no syntax examples or disambiguation beyond what the schema already provides. 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?

States a specific verb ("Get details") and resource ("one dataset"), with the scoping word "one" implicitly contrasting with the sibling datasets_list. It does not name datasets_list explicitly, so sibling differentiation is left to inference.

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 implied by the singular "one dataset" versus the list-oriented siblings, but there is no explicit statement of when to use this tool over datasets_list or explore_datasets, nor any prerequisites such as required permissions or the need for a valid dataset ref.

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 and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context—no pagination, return format, auth requirements, or rate limits—so it earns little credit beyond what structured fields provide.

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, front-loaded sentence with no wasted words. While it is perhaps too sparse for the tool's context, it is structurally clean and concise.

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 two-optional-parameter list tool with rich schema coverage and safety annotations, the description is minimally adequate. However, with no output schema present, it omits any indication of return shape, and it fails to differentiate from siblings, leaving material gaps.

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 both parameters (owner and username) are fully documented in the schema. The description mentions the workspace scope but adds no syntax, precedence rules, or defaults beyond what the schema already states; 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 ('List') and resource ('datasets'), scoped to 'your Ultralytics workspace.' It is clear but does not differentiate from sibling tools like explore_datasets or datasets_get, leaving the agent to infer when this list operation is preferable.

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 no when-to-use guidance, prerequisites, or alternatives. It does not mention explore_datasets, datasets_get, or any condition that would select this tool over other dataset-related siblings.

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 the safety profile (not read-only, not idempotent, not destructive), and the description adds real value on top: the conflictPolicy default of 'skip', the note that the platform default is undocumented, and the async job semantics (returns a queued job id plus current ingest status).

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 dense sentences with no waste; the accepted dataset reference forms and the upload mechanism are front-loaded before the default and follow-up guidance.

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 helpfully characterizes the return (queued job id plus ingest status) and points to the follow-up tool, and it covers all parameters. Minor gaps remain around upload failure/replace semantics, but nothing essential 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 schema already documents all four parameters including the conflictPolicy default. The description adds only the nuance that the platform default is undocumented, which is marginal added meaning over 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 (upload), resource (local dataset archive), and mechanism (signed-upload flow), plus the accepted dataset reference forms. It implicitly separates itself from the sibling uploaders dataset_upload_folder and dataset_upload_video by scoping to an archive file.

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 explicit follow-up guidance ('use datasets_get to follow up') and discloses the default conflictPolicy behavior. It lacks an explicit when-not statement contrasting it with dataset_upload_folder/dataset_upload_video, but 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 cover the write/safety profile (readOnly=false, idempotent=false, destructive=false), so the bar is lower, but the description still adds real value: the async 'signed-upload flow', the default conflict policy with a note that the platform default is undocumented, and the fact that it returns a queued job id plus ingest status. It does not detail permission requirements or failure modes.

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 dense but front-loaded sentences; the purpose leads and the follow-up guidance trails. Minor parentheticals ('the platform default is undocumented') are slightly chatty but earn their place as a caveat.

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 write tool with no output schema, the description covers the essentials: input formats, default policy, async job semantics, and a follow-up tool. Remaining gaps (permissions, idempotency implications, error behavior) are modest given the annotation coverage.

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 baseline is 3 and the schema already documents all four parameters including the conflictPolicy default and targetSplit constraint. The description only restates the dataset ref formats and echoes the conflictPolicy default, adding little 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?

States a specific verb+resource+scope: 'Upload a local image folder as a zip ... for a dataset.' The 'image folder as a zip' phrasing cleanly separates it from the file and video upload siblings, and it enumerates the accepted dataset reference formats. An agent knows exactly what this tool does 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?

Gives clear operational context ('signed-upload flow', default conflictPolicy of skip) and an explicit follow-up path ('use datasets_get to follow up'). It does not, however, explicitly say when to pick this over dataset_upload_file or dataset_upload_video, leaving that choice to the reader.

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 write profile (readOnly=false, idempotent=false, destructive=false). The description adds meaningful context beyond that: the signed-upload flow, that conflictPolicy silently defaults to skip, and that the operation is asynchronous (queued job id + current ingest status). This is good disclosure of a non-obvious default and return timing.

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 dense, front-loaded sentences with no filler; the core action leads and the follow-up pointer trails. Slightly overloaded with parentheticals but each clause 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?

There is no output schema, so the description correctly fills that gap by describing the return (queued job id and ingest status). Combined with the follow-up tool and the conflictPolicy default, it covers what an agent needs to invoke and then track the operation; minor gap on sibling differentiation.

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 3 is the baseline. The description adds value by explaining the conflictPolicy default semantics ('defaults to skip; the platform default is undocumented'), which goes beyond the terse schema wording, and by restating accepted dataset ref formats.

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 ('Upload a local video as extracted frames') and clarifies the mechanism (signed-upload flow). It implicitly distinguishes itself from dataset_upload_file and dataset_upload_folder by scoping to video, but does not name those siblings to make the distinction explicit.

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?

Points to datasets_get for follow-up, which is useful context on sequencing. However, it gives no when-to-use-vs-alternative guidance (e.g. why choose this over dataset_upload_file or dataset_upload_folder for video content), leaving the choice to inference.

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=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds genuinely useful behavior beyond that: the dedupe rule that an unchanged dataset returns the existing version rather than minting a new one. No auth, quota, or return-value details, but the key non-obvious 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?

Two tight sentences, zero filler. The creation action is front-loaded and the dedupe caveat follows immediately as the second-most important fact.

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 two-parameter creation tool with no output schema, the description covers what it does, what input forms are accepted, and the notable unchanged-dataset behavior. Without an output schema the description could have said what the returned version object looks like, which is the only remaining 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 description coverage is 100%, so both parameters are already documented in the schema, and the description's restatement of the accepted ref formats for 'dataset' duplicates that text. The optional 'description' note parameter is not elaborated, so this is baseline territory.

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 and resource ('Create a frozen dataset version snapshot') and enumerates the accepted reference forms. It is clearly distinguished from siblings like datasets_create (dataset creation) and dataset_version_restore (rollback), so an agent can select it without opening another 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?

Gives clear context for when to call it (to snapshot a dataset) and an important conditional outcome (unchanged dataset reuses the existing version). It does not name the closest alternative, dataset_version_restore, or state when not to create a version, 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 flag destructiveHint=true and idempotentHint=false, but the description adds the specifics that matter: exactly what is replaced (images, labels, splits), that un-versioned manual work is discarded, that the operation is itself recoverable by restoring a later version, and the non-obvious post-restore ID behavior (stale IDs return an empty label array rather than 404).

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 ref formats, then destructiveness, recovery, and the ID quirk in dependency order. The 'ships ungated anyway' clause is slightly discursive for a tool description, but each remaining sentence carries operational information an agent needs before a destructive call.

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 two-parameter destructive tool with 100% schema coverage, no output schema, and clear annotations, nothing material is missing: the agent knows the trigger, the ref formats, the collateral damage, the recovery path, and the required follow-up call.

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 both parameters are already fully documented in the schema, including the accepted ref formats and the pointer to datasets_get's versions array. The description largely restates that schema text, adding little semantic detail beyond it, so the baseline 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?

States a precise verb (restore) and resource (dataset version), enumerates the accepted ref formats, and distinguishes itself from siblings like dataset_version_create and datasets_get. An agent can identify it and its counterpart tools without opening any 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?

Routes the agent explicitly: versions come from datasets_get's versions array, and held image IDs must be refreshed via dataset_images_list after the call. It also names the canonical use case (undoing an auto-annotate run) and explains why the tool is ungated, which tells the agent when invoking it is appropriate.

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 readOnlyHint=true and destructiveHint=false. The description adds useful state-dependent behavior: serviceUrl and deployedAt are null until the deployment reaches status ready. It does not cover permissions, error behavior, or broader return semantics, so it is adequate but not rich.

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 tight sentences, front-loads the tool's action, then adds the owner-default and null-field caveat. Every sentence 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 simple one-parameter get tool with read-only annotations, the description covers invocation and one return-state caveat. Without an output schema, however, it still leaves the broader shape of 'details' unspecified, so it is adequate but incomplete.

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% for the single 'deployment' parameter, so baseline is 3. The description adds meaningful information beyond the schema by noting that a bare slug causes the owner to default to the account owner.

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 and resource ('Get details for one deployment'), and the singular 'one deployment' helps separate it from deployments_list. However, it does not explicitly distinguish itself from sibling tools such as deployment_health, deployment_logs, deployment_metrics, or deployment_predict.

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 when-to-use guidance, no mention of alternatives, and no exclusions. The description explains the input reference format but does not help an agent decide when this tool is preferable to sibling deployment inspection tools.

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 and destructiveHint=false, so safety is covered. The description adds real value by clarifying that 'status' is the upstream HTTP status observed at the deployment's own service URL, not the tool-call status — a non-obvious semantic that prevents misinterpretation.

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 tight sentences, front-loaded with the core action and followed by the ref format and status clarification. No filler; every clause 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-param read tool with no output schema and annotations covering safety, the description supplies the input ref format, the owner default, and the meaning of the status value. It stops short of describing error/not-found behavior, but is otherwise complete enough to call 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, but the description adds a genuinely useful detail absent from the schema: a bare slug defaults the owner to the account owner. That default behavior meaningfully augments the single parameter's semantics.

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 ('Probe') and resource ('one deployment's health'), which cleanly distinguishes it from the deployment_get/logs/metrics siblings in the deployment family. An agent can tell what it does 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?

Usage is implied by the word 'health' but the description never states when to prefer this over deployment_get, deployment_metrics, or deployment_logs, nor any exclusions. Adequate but leaves the routing decision to inference.

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, so safety is covered, but the description adds real value: severity is passed through unvalidated and an invalid value surfaces the server's own rejection message, plus the pageToken/nextPageToken return contract. It does not describe ordering or the shape of log entries themselves.

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?

Dense but front-loaded, leading with the core action and following with constraints in descending priority. Every clause carries information, though the severity clause is somewhat long for what it conveys.

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 appropriately documents the nextPageToken pagination contract and the error behavior on bad severity input. Only the log entry return shape and ordering remain unstated, a minor gap for this complexity level.

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, but the description goes beyond the schema by listing illustrative severity values, clarifying that severity is a comma-separated exact match rather than a threshold, and tying the pageToken input to the nextPageToken output 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?

States a specific verb and resource ('Read log entries for one deployment') and scopes it to a single deployment. It is clearly distinguishable from deployment_metrics and deployment_health by resource type, though it never names those 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?

Gives operational context — owner defaults to the account owner, bare slugs are accepted, and pagination walks to older entries — which implies how to drive the tool, but there is no explicit when-to-use-this-vs-sibling guidance against deployment_metrics or deployment_health.

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/non-destructive, and the description goes well beyond them: it discloses the two mutually exclusive response shapes, that they are never merged, which fields each carries, that requests24h is per-hour points not a total, and that range is passed through to the server unvalidated. That is exactly the behavioral context an agent needs.

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 paragraph that is front-loaded with the invocation form and then the response shapes. Nearly every clause earns its place, though the response-shape enumeration is slightly heavy for a definition with 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 carries return-value detail itself, and it does so completely across both shapes. Deployment ref resolution, range default, and validation behavior are all covered, leaving nothing an agent needs 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 meaning beyond the schema: the owner component of a bare slug defaults to the account owner (not stated in the schema) and reiterates that range is unvalidated and default 24h. The sparkline explanation mostly mirrors the schema but frames it in terms of return shape selection.

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 and resource ('Read metrics for one deployment') plus the accepted ref forms. It is distinguishable from siblings like deployment_health, deployment_logs, and model_metrics without opening any 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 explains how to invoke the tool and what each mode returns, but never says when to prefer it over deployment_health, deployment_logs, or model_metrics, and gives no explicit exclusions. Usage is implied by the resource 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?

Adds substantial behavior beyond the annotations (which only say read-only, open-world, non-destructive): verbatim return of images/metadata including undocumented fields, the fact that no per-request cost is documented and costs follow deployment resource configuration, and the cold-start/503 failure mode. This is exactly the context annotations cannot carry.

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 tight sentences, front-loaded with what the tool does, followed by return behavior, cost, and failure handling. Dense but each sentence carries distinct information; 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?

No output schema exists, and the description covers the return shape (images/metadata verbatim), cost semantics, and the primary operational failure mode. For a 5-parameter inference tool with high schema coverage, nothing an agent needs to call 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. The description adds one piece of semantic meaning the schema lacks: a bare slug resolves owner to the account owner, clarifying the ambiguity of the deployment ref. Beyond that it does not restate thresholds or size ranges.

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 (run inference) plus resource (a deployment's own serving endpoint) and input type (local image or video file). It is clear against the deployment_* siblings, though the near-twin model_predict is never named or distinguished.

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 real usage context: cold starts on scaled-to-zero deployments may be slow or 503, and the agent is told to check deployment_health rather than retry blindly. That routes to an alternative tool, but there is no explicit when-not-to-use-this versus model_predict 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 and destructiveHint=false, so the safety profile is clear. The description adds no behavioral context beyond what the annotations provide—no mention of pagination, filtering, or return format.

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, front-loaded sentence with no wasted words. It is appropriately sized for a simple list tool.

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 list operation with one optional parameter and no output schema, the description is minimally adequate. However, it lacks context about when to choose this tool over siblings like deployment_get or models_list, leaving a gap in routing guidance.

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 schema fully documents the optional 'owner' parameter. The description does not mention this parameter or add any semantic detail beyond the schema; 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 (List) and resource (model deployments) with scope (Ultralytics workspace). It clearly distinguishes from single-item tools like deployment_get, but does not differentiate itself from other list tools such as models_list or projects_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?

No explicit guidance on when to use this tool versus alternatives (e.g., deployment_get for a single deployment) or when not to use it. Usage is only implied by the verb 'List'.

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 (destructiveHint=true, idempotentHint=false), the description discloses that stopping preserves URL and configuration, still consumes quota, is a 'money-off switch', and that re-stopping returns a server 400 rather than a false success. This is exactly the behavioral context that annotations alone cannot convey.

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?

Purpose is front-loaded in the first clause, and each following sentence adds distinct, load-bearing information (action payload, side effects, error behavior, reversibility). It is dense, though the 'ships ungated' rationale sentence is the most internal-facing and slightly indulgent.

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 destructive mutation tool with no output schema, the description covers operation, side effects, error semantics, and non-reversibility. An agent has everything needed to invoke it correctly and to understand the consequences.

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 parameter is documented, so the baseline is 3. The description adds real meaning: the owner segment defaults to the account owner and a bare slug is accepted, which clarifies format beyond the schema's restatement.

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 ('Stop a deployment') and clarifies the accepted reference forms (owner/deployment or bare slug). It further disambiguates by naming what this tool does NOT do (start/resize/replace), so an agent can separate it from sibling deployment tools 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?

It explicitly scopes usage ('Sends only {action: stop}'), names unavailable alternatives (start/resize/replace unreachable; reversing via start not in this tool set), and references sibling tools (training_cancel, export_cancel) as precedent for the ungated behavior. It gives clear when-not guidance but not a full routing matrix against other tools.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the 'public' scope and platform, with nothing on result limits, pagination, or ordering behavior beyond what the schema already implies.

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 front-loaded sentence with zero wasted words. It is efficient, though arguably under-specified rather than maximally useful.

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 search with full schema coverage and no output schema, the description is minimally adequate. It omits any note on pagination limits or what a result represents, which would help an agent use the offset parameter correctly.

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

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

Schema description coverage is 100%, with all four parameters (q, sort, task, offset) documented inline, so the baseline is 3. The description adds no parameter syntax or semantic detail 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?

States a specific verb (Search) and resource (public datasets) plus the platform (Ultralytics Explore). The word 'public' implicitly distinguishes it from the sibling datasets_list (the user's own datasets), but it never names that alternative, so the differentiation is partial.

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 explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as explore_projects or datasets_list. The only cue is the word 'public', which an agent must infer as the selection criterion.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping fact that results come from public Explore rather than the user's account, but says nothing about result limits or pagination 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?

A single clean sentence with the search scope front-loaded and zero redundancy. It is efficient, though barely more than a restatement of the tool name plus a scope qualifier.

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 paginated search tool with no output schema, the description leaves the agent without result-format, page-size, or result-count context, and does not distinguish the tool from its many siblings. It is too thin to stand on its own beyond the 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 q, sort, and offset are all documented in the schema itself. The description adds no syntax, format, or constraint detail beyond what the schema already provides, making 3 the correct baseline.

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 (search) and resource (public projects on Ultralytics Explore), which distinguishes it from the private-project siblings projects_list/projects_get. However, it never names an alternative, so the differentiation is only implied by the word 'public'.

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 explicit when-to-use guidance and no mention of alternatives such as projects_list for the user's own projects or explore_datasets for the dataset counterpart. The agent must infer the public-search context purely from the word 'public'.

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?

Goes well beyond annotations (destructiveHint=true, idempotentHint=false) by disclosing the non-atomic check-then-act race, the resulting irreversible artifact deletion, and the dual semantics of the same API verb. This is exactly the kind of behavioral context annotations cannot convey.

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-loads the action and then layers the status-check and race-condition caveats in two dense but purposeful sentences. Every sentence carries information; slightly long clauses make it marginally less scannable than ideal.

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 and full-schema parameter docs, the description supplies the missing behavioral surface — conditional cancellation, refusal on terminal status, and irreversible deletion risk. Nothing an agent needs to call this safely is absent.

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 each parameter is documented in the schema (model ref forms, project required for slug, export id). The description restates the ref forms but adds no format or syntax detail beyond what the schema already provides, so the baseline 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?

States a specific verb+resource ('Cancel an active export job for a model') and enumerates the three accepted model-reference forms, which cleanly separates it from sibling export_create and export_status. An agent can identify the operation 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?

Explains the operating condition precisely: it checks status and cancels only while active, refuses on terminal status, and warns that a finished export is deleted instead. It does not name sibling tools (e.g. export_status) as the way to pre-check, so routing guidance 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?

Annotations only cover the generic profile (not read-only, not idempotent, open-world, non-destructive). The description adds the substantive traits: it is state-changing, it may consume credits, format validation is synchronous while task/architecture compatibility is only determined at run time, and a queued job can still fail. This is exactly the kind of context annotations cannot convey.

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 compact sentences, with the effect ('state-changing, may cost credits') front-loaded in the first, followed by the failure-mode caveat and the routing pointer. Every sentence carries distinct, non-redundant 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 compensates by redirecting the agent to export_status and exports_list for real results, and it discloses the asynchronous failure semantics an agent needs to set expectations. Nothing essential for calling this tool correctly appears to be 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 every one of the eight parameters is already documented in the schema itself, including the model ref forms, project requirement for slugs, gpu_type for TensorRT, and quantize examples. The description's mention of the model reference forms and confirm_cost=true largely restates schema content, so the baseline 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 states a specific verb and resource ('Create a model export job') and enumerates the accepted model reference forms (owner/project/model, ul:// URI, or slug plus project). It is immediately distinguishable from siblings export_status and exports_list, which are explicitly referenced as the outcome-checking path.

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 conditions: use this to create an export job, then use export_status and exports_list for the real outcome, and confirm_cost=true is required. It also warns that success at creation does not imply success at runtime. It stops short of an explicit exclusion against the closely related sibling dataset_export, so a 4 rather than 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?

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds only reference-format details that are already in the input schema, with no extra behavioral context such as pagination, ordering, rate limits, or authorization requirements.

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 front-loaded sentence with no redundant or filler content. Every part of the sentence contributes to identifying the operation and accepted model references.

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

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

For a simple read-only list tool with full schema coverage and safety annotations, the description is nearly complete: it identifies the resource from the operation and accepted inputs. It omits return-related details, but no output schema exists and those details are not essential 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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description reiterates the same reference formats but adds no additional syntax, constraints, or semantics beyond what the schema provides.

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 ('List') and resource ('export jobs') and scopes them to a model via supported reference formats. It is clear on its own, though it does not explicitly differentiate itself from siblings like export_status or export_create.

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 no when-to-use guidance, prerequisites, or alternatives. The agent must infer usage from the listing verb alone, with no routing cues to export_status for a single export or export_create to start one.

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 and destructiveHint=false, so the safe-read profile is covered by structured data. The description confirms it is a status lookup but adds nothing about polling cadence, status values, or terminal states. Adequate but thin given the lower bar set by 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?

A single front-loaded sentence with no filler; the object of the action precedes the identifier list. The phrasing is slightly dense ('plus the export id'), but nothing is wasted.

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 lookup with full schema coverage and no output schema, the description covers what is needed to call it correctly. It could go further by naming the status values or terminal outcomes the job reports, but nothing essential to 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 description coverage is 100%, so the three parameters and the three accepted model-ref forms are already documented in the schema. The description echoes those ref formats rather than adding syntax, constraints, or examples beyond them, so the baseline 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?

States a specific verb and resource: fetching the status of a single export job. The word 'one' sets it apart from exports_list, and the fetch semantics distinguish it from export_cancel. It stops short of explicitly naming those siblings, so a 4 rather than 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?

Usage is only implied: the agent can infer this is for polling a job after export_create and before/instead of export_cancel. There is no explicit when-to-use-versus-exports_list guidance and no stated conditions or exclusions.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is known. The description adds no further behavioral context such as data freshness, rate limits, or auth requirements beyond the bare purpose statement.

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, well-structured sentence that front-loads the action and resource with no wasted 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?

For a zero-parameter, read-only tool with no output schema, the description is sufficient to understand what it does. It could optionally mention the return format (e.g., a list of GPU types with availability counts), but the core purpose is adequately conveyed.

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, so there is nothing for the description to clarify beyond what the empty schema already conveys. Baseline 4 is appropriate for a no-parameter tool.

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 ('Get') and resource ('cloud-GPU stock status') with scope ('by GPU type'). No sibling tool covers GPU availability, so there is no ambiguity to resolve, and the purpose is immediately clear.

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 offers no guidance on when to use this tool versus alternatives, nor any prerequisites or context for invoking it. Usage is only implied by the tool name and description, but no explicit when-to-use statement 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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is already covered. The description adds that the destination is an explicit local path and that a weight file is being downloaded, but it does not disclose overwrite defaults, file-conflict behavior, or other side effects.

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 definition is one front-loaded sentence with no filler. It is somewhat dense because it packs multiple model reference forms into the same sentence, but every clause serves a purpose.

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, annotations cover the write/non-idempotent/non-destructive profile, and the schema fully documents parameters. The description is adequate for invocation but omits operational context such as overwrite behavior and the filename fallback logic, leaving minor gaps.

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 every parameter is documented in the schema. The description repeats the model reference forms already covered by the schema and adds no new syntax, defaults, or edge-case 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?

States a specific verb 'Download' and resource 'trained model's weight file' with destination 'explicit local path'. It clearly distinguishes itself from sibling read/predict tools, but it does not explicitly name alternatives.

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 when-to-use or when-not-to-use guidance and does not name alternatives among siblings. Listing accepted model reference formats is parameter syntax, not task-selection 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 cover the read-only, non-destructive profile, and the description adds substantial behavioral context beyond them: exact null conditions for bestEpoch/bestFitness/bestEpochMetrics, the reason (older Ultralytics versions reported the last epoch as bestEpoch), the caveat that reportedMetrics has no known evaluation provenance, and that resultRecordCount counts records not epochs.

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 the tool's purpose before the dense semantics, and every sentence carries real information. It is long and heavily punctuated, which costs some readability, but there is little that could be cut without losing behavioral detail.

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 full burden of explaining return values and does so comprehensively: field-by-field semantics, null conditions, provenance caveats, and the shape of history output. An agent has everything needed to call and interpret this tool 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, but the description adds value beyond the schema: include_train_args returns 'the full trainArgs object (111 keys observed live)', and include_history 'always states the window it covers, with record counts, the min/max reported epoch, and duplicate and missing epoch numbers' — detail an agent cannot get from the schema alone.

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 and resource ('Report a model's best training epoch and its reported metrics') and immediately scopes it ('works for private and public projects'). It is clearly distinguishable from siblings like training_monitor or deployment_metrics, which concern live training or deployment health rather than a stored model's reported 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 when the fields are populated versus null, which is useful context for interpreting results, but it never names an alternative tool or states when to prefer model_metrics over training_monitor, deployment_metrics, or models_get. Usage is inferable from the resource but not explicitly guided.

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 only cover the read-only safety profile, and the description goes well beyond that: it discloses the default shape-only payload (never values), the exact-as-returned behavior when type is passed, per-type field makeup, and the non-correlation between plot presence and trainResults. That is information an agent cannot get from annotations or schema.

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 the purpose then the default/override behavior, and every sentence carries distinct payload-related information. It is dense and long-sentenced, slightly straining the 'just the essentials' bar, but nothing is padding.

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 supplies the return-shape detail an agent needs: which fields appear per plot type, that values are withheld by default, and the edge case of plots existing independently of training history. Complete for this tool without 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 already 100%, so the baseline is 3; the description earns above it by explaining what type actually changes in the response (full unmodified data vs. a listing) and enumerating valid plot types along with the fields each returns.

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 (report) plus resource (a model's evaluation plots) with the exact set of artifacts named. It explicitly distinguishes itself from model_metrics and training_monitor, so an agent can route without opening a sibling 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?

States the decision rule plainly: omit type to list availability, pass type to get one plot's data unmodified, and the alternative tools do not surface these plots. No inference required.

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, openWorldHint=true and destructiveHint=false, so the safety profile is known. The description adds that base64 inputs bypass the 4,096-char API limit and that MCP client limits may still bite, which is genuinely useful, but it says nothing about runtime cost, GPU usage, or how input is handled server-side.

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, no filler, with the primary action front-loaded and the input-source rule following immediately. 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?

For a 7-parameter inference tool with no output schema, the description covers input selection adequately but omits what the call returns (detections, labels, scores) and how it relates to deployment_predict. An agent can call it, but cannot predict the response shape without experimenting.

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 a real constraint the schema cannot express: source and file_path are mutually exclusive and exactly one must be supplied (the schema only marks model as required). That is value beyond the structured fields.

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 (Run inference) and resource (trained model) and enumerates the accepted input forms, so an agent immediately knows what the tool does. It does not, however, distinguish itself from the sibling deployment_predict, which sounds like the same operation against a deployment.

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 'Give exactly one' usefully constrains source vs file_path, but there is no guidance on when to call this versus deployment_predict, nor on how to choose an image source format. Usage is implied rather than explained.

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 flag destructiveHint=true and idempotentHint=false, but the description adds genuinely useful semantics beyond them: the delete is reversible (goes to trash), and weights, training history, and exports survive until permanent deletion. This materially refines how an agent should weigh the destructive hint, though it says nothing about permissions or required authorization.

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 compact sentences, front-loaded with the action and accepted refs before the reversibility detail. Every clause carries information; the only minor redundancy is restating the ref forms already in the 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?

For a two-parameter mutation with annotations and no output schema, the description covers the key concerns: what is deleted, what survives, and that it is recoverable. Only authorization/permission requirements and any trash-restore path are left implicit, which is a small 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% and the schema already documents both the model ref forms and the project requirement for slug refs, so the description largely repeats what is structured. Baseline 3 is appropriate; it adds no syntax examples beyond the schema's own wording.

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 (soft-delete) plus the resource (model) and enumerates the three accepted reference forms inline. An agent can immediately tell this is a deletion of a model, not of a project, dataset, or deployment.

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 clarifies the accepted reference forms and that the action is a soft delete, but it gives no explicit when-to-use guidance or routing to an alternative (no permanent-delete sibling is named, and the relationship to models_get/models_list is unstated). Usage is implied rather than prescribed.

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 and destructiveHint=false. The description adds real behavioral context beyond that: it discloses a scope limitation (best epoch/fitness excluded) and names the tool that does provide it, which prevents a misled empty-result interpretation. No auth, pagination, or return-shape detail, keeping it at 4.

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 tight two-clause sentence: the core action and accepted ref formats come first, the exclusion and pointer to model_metrics last. 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?

For a two-param read tool with no output schema, the description covers the key pitfall (missing quality fields) and directs to the right alternative. It could be more complete with a note on what is returned, but annotations and the schema carry the safety and parameter burden adequately.

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 parameters (model, project) are already documented with the same ref-format and slug-requires-project rules. The description largely restates this, adding no syntax or format detail the schema lacks. Baseline 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?

States a specific verb+resource ('Get details for one model') and enumerates the accepted reference forms (owner/project/model, ul:// URI, or slug with project). It also carves out its boundary against the sibling model_metrics, so an agent can select it 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 tells the agent this tool does NOT return quality data and routes that need to model_metrics, which is genuine when/when-not guidance. It stops short of stating prerequisites or alternatives for other model-listing/detail cases (e.g. models_list).

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine scope disclosure by stating what the return does NOT contain (model quality), which is real behavioral context beyond the annotations, though it says nothing about pagination or result ordering.

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 tightly packed sentences with zero waste; the core purpose and identifier forms lead, and the exclusion/alternative note follows. Every clause 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?

No output schema exists, and the description partially compensates by stating what the result omits and where to get that data instead. Neither pagination behavior nor return shape is explained, but for a simple read-only list tool with fully-covered parameters, the coverage is nearly 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 description coverage is 100%, so both parameters (project and limit, including the default-20/up-to-100 nuance) are fully documented in the schema. The description restates the accepted project identifier formats but adds no meaning beyond the schema, so the baseline 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?

States a specific verb and resource ("List models in a project") plus the accepted identifier forms, and distinguishes itself from siblings by explicitly noting that model quality is excluded. An agent can tell this apart from models_get, model_metrics, and model_plots without opening any 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?

Names the alternative (model_metrics) and the condition that selects it (when you need quality / best-epoch validation). It does not explicitly contrast against models_get for single-model retrieval, so routing is clear but not complete.

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 cover the safety profile (not read-only, not idempotent, not destructive), so the bar is lower, but the description adds real value by disclosing that this tool defaults to private visibility while the platform itself defaults to public when visibility is omitted — a non-obvious divergence an agent must know. It stops short of mentioning duplicate-slug errors, auth requirements, or whether the created project is returned.

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 waste: purpose first, then the one caveat that changes agent behavior. Perfectly front-loaded.

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 fully documented create tool with annotations covering the mutation profile and no output schema to explain, the description covers what is needed. The remaining gap is failure/ownership edge cases (slug uniqueness, owner defaults), which are secondary.

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 five parameters are already documented, including the private/public default for visibility. The description reinforces the visibility default but adds no syntax, constraint, or meaning beyond what the schema states; baseline 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?

States a specific verb and resource ('Create a project') scoped to the Ultralytics workspace, which is unambiguous. It does not explicitly name or contrast with the sibling read/delete tools (projects_get, projects_list, projects_delete), but the verb makes the distinction self-evident.

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 use this tool versus alternatives, no prerequisite conditions (e.g., workspace permissions), and no guidance on how it relates to projects_get/projects_list. The only contextual note concerns visibility defaults, which is behavioral rather than usage routing.

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 flag destructiveHint=true and readOnlyHint=false; the description adds real value beyond them by disclosing that this is a SOFT delete, that the project lands in trash, and that it stays restorable for a bounded window. The only gap is that the window length and permission requirements are unspecified.

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, no waste, and the most important fact (soft-delete with a restorable window) is front-loaded right after the verb. Every clause 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?

With no output schema, the description still conveys the essential outcome (trash, restorable) for a single-parameter mutation tool. What is missing is concrete detail on the restorable window and any confirmation of what the call returns on success.

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 the single parameter is fully documented in the schema, so the description's restatement of the accepted ref formats adds no new meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Soft-delete a project') plus the accepted identifier forms (slug, owner/slug, ul:// URI), which lets an agent identify the tool without opening the schema. It is clearly distinguishable from projects_create, projects_get, and the datasets_delete siblings.

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 (removing a project) and hints at recoverability, but never states prerequisites, when to prefer an alternative, or how it differs from hard deletion. Usage is inferable rather than specified.

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 and destructiveHint=false, so the safety profile is covered. The description adds only the accepted identifier formats; it says nothing about behavior on a missing/ambiguous ref (error vs empty), auth requirements, or output shape, so it adds modest value 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?

One short sentence, front-loaded with the verb and resource, with the identifier forms appended. 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?

For a single-parameter read tool with annotations covering the safety profile, this is largely complete; no output schema exists but none is needed. The only gap is the absence of any routing guidance against the many sibling get/list/explore tools.

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 single 'project' parameter is already documented as 'Project ref by slug, owner/slug, or ul:// URI.' The description essentially repeats that wording, adding no new semantics, so baseline 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?

States a specific verb ('Get') and resource ('one project'), and identifies the accepted identifier forms (slug, owner/slug, ul:// URI). It implicitly contrasts with list-style siblings like projects_list and explore_projects by saying 'one project', but never names an alternative 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?

Usage is only implied: an agent can infer this is for fetching a single project's details. There is no stated when-to-use vs when-not, no mention of when to prefer projects_list or explore_projects, and no prerequisites called out.

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 and destructiveHint=false, so safety is covered. The description adds only the workspace scoping context and nothing about pagination or default result size, leaving the behavioral burden mostly unmet for a tool whose output size is variable.

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 efficient sentence with the resource front-loaded and no filler. It is appropriately sized, though it is essentially the minimum rather than a model of structure.

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 list tool with full schema coverage and no output schema, the description is barely adequate: it omits result ordering, pagination expectations, and how it differs from explore_projects. The gap is minor but real given several look-alike siblings.

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 limit, owner and username are fully documented in the schema including defaults and precedence. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the work.

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 computer-vision projects') with a scope qualifier ('in your Ultralytics workspace'). It does not differentiate from siblings like explore_projects or projects_get, so the agent must infer the distinction.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as explore_projects or projects_get. The explicit 'list all projects' framing is only implied by the verb.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description goes further by disclosing that the compute instance is released, elapsed GPU time is still charged, and the most recent checkpoint is preserved rather than discarded – genuine side-effect detail 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?

Three sentences, front-loaded with the action and reference forms before the side-effect details. Every sentence earns its place, though the closing 'does not delete the model' is slightly redundant with the checkpoint-preservation statement.

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 two-parameter cancel tool with no output schema, the description covers the reference forms, compute release, billing behavior, and checkpoint preservation. It omits permissions/auth requirements, but is otherwise complete enough to call correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description restates the accepted reference forms (owner/project/model, ul:// URI, or slug with project) but adds no syntax or format detail beyond the schema, so the baseline 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?

States a specific verb ('Cancel') and resource ('a running training job'), and explicitly distinguishes itself from deletion with 'This stops the job and does not delete the model.' This clearly separates it from siblings like training_start, training_monitor, and models_delete.

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 clarifies scope (stops but does not delete), which implicitly routes deletion to models_delete, and explains the accepted reference forms. However, it never explicitly states when to use this versus alternatives or any preconditions (e.g. job must be running), leaving usage to inference.

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 only cover the safety profile (readOnlyHint, openWorldHint, destructiveHint false); the description adds substantial behavioral context beyond that: counter pass-through semantics, the post-training-evaluation epoch inflation, nonzero etaMs after completion, the 'unavailable rather than inferred' behavior with no job, and record-ordering quirks. This is exactly the kind of caveat an agent cannot get from structured fields.

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 every sentence carries a non-obvious caveat, so little is wasted. However, the dense single paragraph mixes response-field semantics without any grouping, which makes it harder to scan than a structured list would be.

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

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

There is no output schema, so the description must carry the full burden of explaining return values, and it does: it defines reportedCurrentEpoch, reportedProgressPercentage, etaMs, resultRecordCount, lastReportedMetrics, timing.elapsedMs, and computeCost.durationMs, including their edge cases. Nothing an agent needs to interpret a monitor response 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 all four parameters are already documented in the schema (including the history_last_n truncation window semantics). The description mostly elaborates on return fields rather than adding meaning to parameters, 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?

States a specific verb and resource ('Report a model's training status and progress') and scopes it to private and public projects. It also implicitly separates itself from the sibling model_metrics by declaring that model quality belongs there, so an agent can distinguish the two 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?

Provides clear context for use (monitoring a training job's progress and status) and explicitly routes the quality-evaluation need to model_metrics. It does not state when NOT to use it versus training_start/training_cancel, but the read-only monitoring intent 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?

Annotations declare destructiveHint=true and openWorldHint=true; the description goes far beyond them, disclosing that billing starts immediately with no cost preview, that dataset validation rejects unusable data before compute, that history replacement is irrecoverable while uploaded weights survive, and that checkpoint mode can leave an orphan model behind. This is exactly the destructive/auth/cost context annotations cannot express.

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 requirements, and every section carries real information about a genuinely complex destructive operation. It is dense and mildly repetitive (the cost-without-preview and history-loss points are each re-stated), which keeps it from a 5.

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 an 11-parameter destructive tool with no output schema: it covers billing timing, confirmation flags, the task-mismatch orphan-model risk with a recovery path (models_delete), and the sibling used to cancel. Nothing an agent needs to invoke it safely 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 baseline is 3; the description still adds value by explaining the conditional requirement of confirm_history_loss (not needed for untrained models or checkpoint mode) beyond the schema's own text, though it largely restates the confirm_cost meaning already in 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 ("Start a cloud training job") and enumerates the two input modes (existing model vs official YOLO base checkpoint). An agent can distinguish this from training_cancel, training_monitor, and model_predict without opening any 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?

Clearly routes the opposite action ("Use training_cancel to stop a job that is already running") and specifies the confirmation conditions that gate each path (confirm_cost always, confirm_history_loss only for re-training a model with a recorded run). It stops short of an explicit 'do not call this when...' exclusion list, but the context for use is unambiguous.

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