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

Annotations cover the safety profile (destructive, idempotent, non-read-only), and the description adds value beyond them: cancellation granularity (mid-step work completes and still bills), the specific error code for ended runs, and the credential requirement. That is meaningful operational context an agent needs before invoking.

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 core action, then constraint, then failure mode and prerequisite. No filler; every 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, yet the description supplies the relevant return behavior (WORKFLOW_RUN_NOT_CANCELLABLE) and billing consequence of a partial cancel. Combined with the annotations, an agent has everything needed to call this 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% and run_id is fully documented in the schema with its `wf:…` format. The description adds no parameter-level detail, 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 a workflow run') and immediately narrows scope with 'Cancels between steps only'. It does not explicitly name or contrast with siblings like run_workflow or check_workflow_run, so it falls short of full sibling differentiation.

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 and boundaries: cancellation only occurs between steps, an already-ended run returns WORKFLOW_RUN_NOT_CANCELLABLE, and a Relay credential is required. It stops short of explicitly naming alternative tools or when-not-to-use-this-instead scenarios.

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 readOnly/openWorld/idempotent annotations, it discloses genuinely useful traits: no authentication key is required, the call blocks for at most 30 s, incomplete calls return status rather than results, and results expire 1 h after completion. These are non-obvious operational facts an agent could not infer from the annotations or schema, and they are consistent with the declared hints.

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

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

Three tight sentences with the core behavior front-loaded and no filler; the retention, wait and polling-loop facts each earn their place. The punctuation is slightly dense (a parenthetical plus a colon splice), which marginally hurts readability.

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 carries the return-value burden itself and does so: it states that a completed task returns the result and an incomplete one returns status, plus how long results remain retrievable. For a 3-parameter polling tool, 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 description coverage is 100%, so the schema already explains task_id, wait_seconds (0–30, default 30) and inline_images. The description restates the 30 s wait but adds no format or edge-case meaning beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb+resource ('Checks a task') and ties it directly to the tool that produced it ('a task run_model returned'), which cleanly separates it from siblings like check_workflow_run. The parenthetical 'no key needed: the task_id is the capability' further pins down the exact identifier it operates on.

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 explicit polling guidance: wait up to 30 s, and if it isn't done, 'call check_task again, never resubmit.' That directly answers the when-to-use-again question. It doesn't explicitly name or exclude the alternate workflow-checking sibling, so it falls just short of a 5.

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

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

With no output schema, the description carries the burden and does so well: it maps every terminal state to a result (completed → final output, failed/cancelled → error, running → steps so far) and discloses the auth model ('the run_id is the access token'), which is behavior the readOnlyHint/openWorldHint annotations do not cover.

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 action, then the outcome mapping, then the auth note. The arrow notation ('Completed → ...; failed / cancelled → ...') packs three branches into one sentence with zero 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?

For a two-param polling tool with no output schema, the description covers everything an agent needs: how to wait, what each outcome returns, how to continue polling, and why no key is required. Nothing material 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 both params (baseline 3). The description adds meaning beyond the schema by framing run_id as the access token and reinforcing the wait_seconds cap and polling contract, which is useful context the schema alone doesn't 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 and resource ('Poll a workflow run by run_id') and immediately clarifies it is a polling/status tool, which cleanly separates it from siblings like run_workflow, cancel_workflow_run, and list_workflows. An agent knows 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?

Gives explicit runtime guidance: wait up to wait_seconds, and if the run is still going, 'call check_workflow_run again'. It also ties run_id to its origin ('returned by run_workflow' in the schema). It does not name a when-not case or an alternative (e.g., cancel_workflow_run), so it stops short of a 5.

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

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

Annotations already declare readOnly/openWorld/idempotent, so the bar is lower, yet the description still adds real context: the estimate may diverge from the invoice due to provider-reported usage and account-specific custom pricing, and pricing depends on the caller's tier and grants (public otherwise). It also documents defaults and that relay1h and provider storage are free. Missing: the returned structure.

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 estimate-vs-invoice caveat is front-loaded within the first sentence and there is no filler; however, the heavy nested-parenthesis construction and the long comma-run of billing-type field lists make it dense to parse.

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

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

With no output schema, the description carries full responsibility for describing the return value, and it only says it 'estimates the USD cost' without indicating a total vs. an itemized breakdown, currency/rounding, or what happens for an unpriced model or unsupported billing_type. Inputs are thoroughly covered, so the omission is on the output side only.

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 per-field descriptions already carry the definitions; the description's contribution is organizing fields by billing_type and instructing the agent to pass only the relevant subset, which is useful but largely restates the schema's existing 'per_token:'/'per_second_video:' prefixes. It adds the storage-fee trio (store_output/retention/file_count) grouping but little beyond that.

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

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

The opening clause gives a specific verb (estimates) and resource (USD cost of a call from the price list), which is clearly distinct from get_pricing (returns the list) and get_usage (actual billed usage). An agent can distinguish it from every sibling without reading the schema.

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

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

It explicitly directs the agent to consult get_model or get_pricing to find the model's billing_type, and warns off misuse by stating the result is an estimate, not an invoice, with the bill driven by provider-reported usage. It does not state a hard when-not (e.g., 'do not use to reconcile spend, use get_usage'), so it stops short of full alternative 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral detail beyond that: the credential tiers accepted and the concrete failure mode (PERMISSION_DENIED 403 for a plain inference key). It stops short of describing return shape, but adds real value.

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 that front-load the resource and then the auth constraints. Slightly repetitive with two consecutive 'Needs ...' clauses, but 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 zero-parameter read with no output schema, the description covers what is returned (balance, promo credits, consumption) and what credentials are required. Sufficient for correct invocation, though it could be more explicit about the account/workspace scope of the read.

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 per the rubric the baseline is 4. There is nothing for the description to compensate for, and the schema is trivially complete.

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 ('Read') and a precise resource set: credit balance, active promo credits, and consumption. This is clearly distinct from sibling cost/usage tools like get_usage, estimate_cost, and get_pricing, so an agent can select it without opening the schema.

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

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

The description gives access prerequisites (dashboard JWT or custom-tier superkey; Relay credential) but no guidance on when to prefer this over get_usage or estimate_cost. Usage context is implied by the resource, not made 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 supply readOnly/idempotent/openWorld; the description adds genuinely new behavior: the response is auth-dependent ('with a credential the answer is your account's view ... public otherwise'), which materially changes how the agent should interpret results. Missing rate limits or how availability is expressed, so not a top score.

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 the return fields, followed by the credential caveat and the follow-up action. Nothing is repeated and 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?

There is no output schema, and the description compensates by enumerating the returned fields and explaining the account-vs-public variability. For a one-parameter read tool, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% with a single required parameter already documented as 'Exact model name from search_models, e.g. ...'. The description does not add format or naming guidance beyond that, so the schema does the work; 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?

Names a specific verb and resource ('Returns one model's route, request_schema, request_example, pricing and availability') and enumerates exactly what comes back. This clearly separates it from search_models (discovery) and get_pricing (cost-only) without the agent needing to open 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?

"Then call run_model with an input shaped like request_example" gives an explicit next step and sequencing, which is strong guidance. It stops short of naming when to prefer search_models first (only the schema carries "Exact model name from search_models") or when to skip get_model in favor of get_pricing, so no exclusion rules.

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 read-only, idempotent and open-world traits, so the bar is lower, and the description still adds real context: results differ depending on whether a credential is supplied (account tier/grants view vs public list prices) and it names the media_storage section of the response. It does not describe response shape in detail or ordering, keeping it below 5.

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 main purpose in the first clause, which is good. However, the nested parenthetical 'with a credential your account's view: its tier and grants; public otherwise' is dense and awkward to parse, and the final fragment 'Then estimate_cost for a number' is clipped. Information-dense but not cleanly structured.

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 the return-shape burden and does reasonably well: it names USD list prices, per-model rows, and the media_storage per-file fee section with example SKU names. What is missing is any indication of row structure or volume for the no-model case, which matters for an open-world read.

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?

With one optional parameter at 100% schema coverage, the schema already documents the model filter including the 'omit for every model' behavior. The description adds the nuance that credentialed calls return the account's own tier/grants pricing, but that is about the call context rather than the parameter itself. 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 ('Returns Relay's list prices (USD)') and enumerates the payload sections (per-model rows, media_storage per-file fees for retention SKUs). It also names the sibling it is not ('Then estimate_cost for a number'), so an agent can distinguish it from the cost-calculation tool. The parenthetical about credentialed vs public views muddies it slightly but the core purpose is unmistakable.

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

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

Explicitly routes the agent: call this to get price data, then call estimate_cost to turn it into a number. It also states the model-omission behavior ('Omit for every model'), which is a usage rule. No explicit when-not beyond that, so it stops short of a 5.

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

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

Annotations only supply readOnlyHint and openWorldHint, but the description adds the auth/authorization profile (dashboard JWT or custom-tier superkey; plain inference key returns PERMISSION_DENIED 403), the Relay credential requirement, and pagination mechanics including the next_cursor handoff. Those are the details an agent most needs before calling and are not available in 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?

Three tightly packed sentences with the core purpose front-loaded and no filler. The parenthetical pagination and auth clauses are dense but each carries operative information; a small readability cost from cramming them into a single flow.

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 hints at the return shape via 'the previous answer's next_cursor', and it covers auth, credential requirements, pagination, and the two query modes. An agent has everything needed to call it correctly and iterate through pages.

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 every parameter is already documented with its format and bounds. The description largely restates the schema (limit up to 1000, period max 30d, from+to pairing), adding only the 'newest keys first' ordering and the pagination workflow, which earns baseline rather than above-baseline credit.

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 the account's usage and spend per API key') plus the sort order and page size. It is clearly distinguishable from sibling tools like get_credits, get_pricing, and estimate_cost, which concern balance, rates, and projection rather than per-key spend.

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 conditions for the alternative parameter modes: use period for a by-date breakdown, or from + to for an explicit range, and warns that only dashboard JWT/custom-tier superkeys can call it. It does not name which sibling to use instead for related questions (e.g. get_credits for remaining balance), so it falls just 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 cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description's burden is lighter. It nonetheless adds real value by disclosing the shape of each returned entry (workflow_id, input_schema, steps with step_id + model), which is important because there is no output 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?

Two dense sentences with no filler; the identity/shape of the resource is front-loaded and the follow-up action (run_workflow) comes last where an agent expects it.

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-param, read-only listing tool with no output schema, the description covers the essential return fields and the next step. It omits minor context such as scope (are templates global or workspace-specific) or expected volume, but nothing that would cause a mis-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?

The tool takes zero parameters, so the baseline is 4. The description's mention of input_schema refers to the listed workflows' schemas rather than to this tool's inputs, so there is no parameter semantics to clarify.

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 Relay's workflow templates') and immediately defines what a workflow template is (multi-step pipeline run as one call), which distinguishes it from run_workflow, check_workflow_run, and cancel_workflow_run.

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 routes the agent onward: 'Run one with run_workflow; inputs follow input_schema.' That names the alternative tool and the handoff condition. It does not state when this listing tool itself is preferred over other discovery tools, so it falls short of full when/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 say it's a non-read-only, open-world, non-idempotent call; the description adds the material behavior: billing to the caller's key, a 45 s wait ceiling before returning a task_id, inline vs. task submission by schema type, 1 h link expiry, and the idempotency replay/422 semantics. That is substantially more than the annotations 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?

It is front-loaded with the core action and scope, and every clause carries operational content, but the prose is dense and run-on ('45 s', '1 h', SKU references) in places. Slightly more sentence splitting would improve scanability without losing 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 6-parameter, open-world, mutating tool with no output schema, the description covers what matters: how to build input, what the return looks like (inline answer vs. task_id), how long result links last, and how to extend retention. Nothing an agent needs before invoking it 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?

With 100% schema coverage the schema already documents each parameter, so the baseline is 3. The description still adds cross-tool guidance for constructing `input` (follow get_model's request_schema, request_example runs as is) and ties store_output to a media_storage SKU from get_pricing, which the schema alone does not connect.

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

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

The opening sentence states a specific verb and resource ('Runs any Relay model by name') and immediately marks it as billed, which distinguishes it from the free/metadata siblings like search_models and get_model. The model-by-name framing implicitly separates it from run_workflow.

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 names concrete alternatives and the conditions selecting them: call check_task instead of resubmitting a timed-out async task, pass idempotency_key if you may retry, and use store_output/get_pricing when results must outlive the 1 h expiry. It also states the credential prerequisite, so no routing decision 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 only covering safety/openness flags, the description adds substantial behavioral context the annotations cannot: per-step billing ("each step is billed as an ordinary request"), the cost of a mistaken resubmit, the single signed webhook.completed / workflow.failed delivery, and the Relay credential requirement. These are exactly the cost- and side-effect facts an agent needs before invoking a billable, non-idempotent submit.

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 most decision-relevant facts (submit, wait, follow-up, billing) are front-loaded in two dense sentences with semicolons and no filler. It is slightly run-on and could be split, but essentially every clause carries information the agent needs.

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 billable async submit with six parameters, nested inputs, and no output schema, the description covers the return dichotomy (final output vs. run_id), the follow-up path, idempotency-adjacent behavior, webhook semantics, credential prerequisites, and where to obtain inputs. Nothing needed 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 still adds cross-tool guidance the schema cannot supply, telling the agent that workflow_id and the inputs shape come from list_workflows, and framing wait_seconds as a wait budget rather than a bare integer. It adds modest but real semantic value on top of the well-documented schema.

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

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

The first clause gives a specific verb + resource + scope ("Start a workflow run (one submit) and wait up to wait_seconds (≤ 45)"), which immediately distinguishes it from siblings like run_model (single model call) and check_workflow_run (status polling). An agent knows exactly what operation this is without opening the schema.

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

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

It explicitly routes the agent: if the run is still going, "call check_workflow_run with it, never resubmit (a new run bills again)", and it points to list_workflows for workflow_id and input shape. It names the alternative tool and the condition that selects it, plus the correct behavior on the negative outcome.

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

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

The annotations declare readOnlyHint and openWorldHint=false, and the description corroborates that with 'bundled, offline', telling the agent results come from a local corpus with no network dependency. It also discloses the return shape (page, heading, docs path with anchor, excerpt), which the annotations do not cover. It says nothing about ranking/recency or corpus staleness, keeping it below a 5.

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: purpose and corpus scope first, then return shape, then sibling routing. Every sentence carries distinct information with no redundancy or 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?

There is no output schema, so the description's enumeration of returned fields ('page, heading, docs path with anchor and an excerpt') is genuinely necessary and present. With only two fully documented parameters and annotations covering the safety profile, nothing an agent needs to call this 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 both parameters (query, limit) are already fully documented in the schema, including the 1-10 range and default. The description adds no syntax, format, or query-construction guidance beyond what the schema states, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Search Relay's public docs') and scopes what is searchable (how-to, auth, errors, limits, retries, webhooks, files, pricing rules), plus the offline/bundled nature. It explicitly distinguishes itself from two siblings (get_model, search_models), so an agent can route correctly 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?

It gives explicit routing: 'For a model's input fields use get_model instead; to find a model use search_models.' That resolves the main ambiguity against siblings. It stops short of stating when-not to use this tool (e.g. that it does not cover private/internal docs beyond the listed topics), so it is clear context without full 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 readOnly/idempotent/openWorld, yet the description still adds real value: a hard result cap ("at most 50"), the fact that visibility differs with and without a credential, and the exact per-model return fields. It omits pagination/truncation behavior and says nothing about rate limits.

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, then capabilities, then return shape, then the next step. The tag enumeration is long but earns its space as the only source of that vocabulary; a couple of clauses could still be tightened.

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, it supplies return fields, the result cap, the auth-dependent scoping, and the next call to make. An agent has everything needed to invoke it and act on results.

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 goes beyond it by enumerating the valid tag vocabulary (absent from the schema's enums) and by clarifying that image-to-image deliberately widens to all image-in models. The query semantics are already in the schema, so the gain is partial rather than decisive.

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?

Opens with a specific verb and resource ("Lists Relay models by tag and/or text") and explicitly separates itself from get_model, which it names as the follow-up for input schemas. An agent can distinguish it from run_model or get_pricing 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?

Gives a clear two-step flow ("Then call get_model with a name for its input schema") and explains the credential-dependent view. It stops short of naming exclusions against other siblings such as get_pricing or list_workflows, but the usage context is unambiguous.

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

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

Annotations only say this is a non-read-only, non-destructive, non-idempotent open-world call; the description adds the material context — size ceilings per input mode, the daily free quota on relay1h, and the requirement for a Relay credential. It stops short of saying whether repeated uploads of the same file create distinct URLs or can be cleaned up, which is the remaining gap for a write tool.

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 paragraph: outcome first, then how to consume the result, then the input constraint, then retention policy, then the credential prerequisite. No sentence is 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?

For a 6-parameter upload tool with no output schema, it covers the full lifecycle an agent needs: what gets hosted, what URL comes back, where that URL goes next, size/transport limits, retention options and the auth prerequisite. Nothing required to invoke 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 per-parameter text is already present. The description still adds value the schema cannot express: the exclusive-or relationship among path/base64/url (the schema has no oneOf) and the size limits restated at the decision point. The slot parameter is left entirely to the schema, which is acceptable since it is well documented there.

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 ('Hosts an image, video or audio file on Relay and returns its url') and immediately names the consumer of the output ('any *_url input of run_model'). This distinguishes it from every sibling, none of which handle file hosting.

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

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

Gives an explicit decision rule for the three mutually exclusive inputs ('Give exactly one of path, base64 or url'), scopes path to local server only, caps base64 at 4 MB and routes larger/published files to url. It also points to get_pricing for non-default retention, so the agent knows where the alternative lives.

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