looot

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value: a pending Stripe Checkout session may be returned, reading never opens a session, and minimumUsd is a purchase minimum rather than a required balance — contextual traits not present 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?

Purpose is front-loaded, but the text is dense and slightly redundant — 'reading the balance never opens one' and 'This tool reads only and opens no payment session' restate the same point, and the minimumUsd/balance_sufficient clarifications could be tighter.

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 no parameters, the description carries the full burden and largely meets it by explaining the meaning of returned fields and the caveats around pending sessions and minimums. Return-shape details (reserved vs. available units) remain lightly specified.

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?

Zero parameters, so the 4 baseline applies per the rubric. The description instead documents response-field semantics (topUpLink, dashboardUrl, balance_sufficient), which is a bonus but not a parameter concern.

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 ('check the balance: available and reserved balance for a workspace'), and scopes it precisely against the write-side sibling by noting it opens no payment session, distinguishing it from top_up without ambiguity.

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?

Offers interpretation guidance (balance_sufficient means positive funds, not affordability; compare a run's estimated cost against available balance) but never states when to call this vs. alternatives such as top_up or run. Usage context is implied by the read-only framing rather than spelled 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 idempotentHint=true, readOnlyHint=false and destructiveHint=false, so safety is largely covered. The description adds real value by explaining the mechanism behind idempotency ('makes a retry a no-op instead of a duplicate ask'), but says nothing about auth/permissions, any review or approval flow after submission, or limits on how often requests can be filed.

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

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

A single dense sentence with three tight clauses, front-loaded on the purpose before the parameter notes. No filler, though the em-dash chaining is slightly run-on and could be split for scannability.

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 creation tool with no output schema, the description never says what comes back (a request id? a status?), nor what happens next (review, fulfillment, polling via my_tools). It covers inputs adequately but leaves the post-call lifecycle and return value entirely to inference.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: it clarifies that title/description are free-form author content, that desiredInputs/desiredOutputs are optional field lists the target endpoint should take/return, and that idempotencyKey is caller-supplied and must be stable per request. Only the trivial title/description field constraints (length limits) are left to 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 and resource ('request a provider or job') and pins the scope to things 'the data API catalog does not cover yet', which cleanly separates it from catalog-reading siblings like search_catalog, discover, and catalog_overview. The endpoint equivalence (POST /v1/capability-requests) gives an unambiguous anchor.

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 'does not cover yet' condition is an explicit when-to-use trigger that implies the reader should first check the catalog tools. It stops short of naming the specific alternatives (search_catalog/discover) or stating when-not to file a request (e.g., duplicates), 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?

Annotations only establish that this is a safe, idempotent read; the description adds substantial behavioral context beyond them: approximate payload sizes per depth, the 25-job cap with a 'truncated' flag, unknown_category/unknown_platform responses for bad ids, that branch queries carry no totals, and that depth is incompatible with topic.

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 and every clause carries useful detail (sizes, caps, error ids), but the density of nested parentheticals makes it a single packed block that is harder to scan than it could be. No genuinely wasted sentences, so only a small deduction.

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 return-value burden, and it does: it enumerates the count fields, explains null pricing, describes the truncation flag, and specifies the error-shaped answers for unknown ids. An agent has everything needed to call it and interpret 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, but the description adds real cross-parameter semantics the schema lacks: depth defaults change depending on whether category/platform is supplied, depth is not valid with topic, and what each value actually returns. It stops short of exhaustively restating each parameter, which 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+resource (overview of the data API catalog) and then precisely defines the resource's shape: categories > platforms > jobs with counts at every level. It is clearly distinguishable from siblings search_catalog, discover, and search, which it explicitly positions itself as a precursor to.

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 usage branching: no arguments = summary, depth platforms/jobs/full for more, category or platform to scope a branch, topic for keyword jobs. It also names the alternatives and when to move on ('Follow up with search_catalog or discover to pick an endpoint for a job').

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

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

Annotations already mark this readOnly, idempotent, non-destructive and closed-world, and the description adds substantial behavior beyond them: it never returns a mock endpoint, minimumScore is applied before resultLimit, identity modes never substitute endpoints/providers, and it enumerates the exact warning strings emitted when supply or price filters empty the result set.

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 core definition (free, up to 5 endpoints, search axes) before the operational detail, and the dense length is largely justified by 18 undocumented parameters. Some clauses are awkward and packed, but little is pure repetition.

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

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

For an 18-parameter tool with no output schema and no per-parameter schema docs, the description covers the return shape well (the `title` field list, `full` candidate `credential` and `facts`), the failure modes, and the key controls. A few filter parameters and the relevance/evidence/availability/price component semantics remain only partially explained.

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 18 parameters at 0% schema description coverage, the description carries the full load and does explain the high-value ones: `mode` values, `detail` (and that it never affects ranking), `prefer`/`ranking` alias, `minimumScore` ordering, and `jobInputs` field-name semantics. It leaves several parameters unaddressed, notably `eligibilities`, `executionModes`, `allowedProviders`, `blockedProviders`, and `includeUnavailable`, so the coverage is strong but incomplete.

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 (free search of the data API catalog) plus a hard scope (up to 5 eligible endpoints) and the axes it searches by. It explicitly differentiates itself from the sibling `search` (more than 5 results / whole category) and `discover_smart` (sentence-described jobs), so an agent can pick it without opening other schemas.

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

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

Gives explicit when-to-use routing: use `search` for >5 results or a whole category, and `discover_smart` when the job is best described in a sentence and nothing here is a confident match. It also states the constraint that identity modes never substitute another endpoint or provider, which bounds how results may be trusted.

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 far beyond the annotations: discloses cost model (per-token billing, ~$0.00005 typical, ~$0.0004 cap, still billed if a timed-out run reached the provider), latency, the two-stage pipeline, the never-errors degraded contract with its specific reason values, and the job-first skip semantics. Annotations only say readOnly=false/openWorld=true/non-idempotent; the description supplies the substantive risk and billing 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?

Front-loads the money warning and the cheaper alternative, then structures the mechanics as (1)/(2). Dense but nearly every clause carries operational detail; it is long, and a few parentheticals could tighten, but there is little 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 no-output-schema, paid, multi-stage tool it covers return shape (candidates ranked by probability with lexicalRank, `smart` winner/confidence/runId/cost), failure/degradation paths, and billing surface. An agent has everything needed to call it, interpret results, and handle failure.

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 0%, so the description carries the burden. It clarifies `useCase` semantics (the job intent that Jev judges against) and implies `maxPriceMicros` via the priceHint/price-filter note, but never defines `query` vs `useCase`, `candidateLimit`, or the other filter fields. Partial compensation only.

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+resource+scope: a paid, two-stage semantic search of the data API catalog that judges a lexical shortlist against a use case. It explicitly distinguishes itself from the sibling `discover` (free, lexical) and names the condition that separates them, so an agent can route without opening either 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 when-to-use ('only reach for this when a lexical search cannot express the job'), the required first step ('use `discover` (free, instant) first'), and a concrete worked example. It also covers when the tool self-skips (single clear job) and what to do after (follow up with inspect/run).

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 (readOnlyHint=false, destructiveHint=false, non-idempotent), and the description adds substantial context beyond that: it is free/never charged, rate-limited to 20 per day per workspace with the specific error feedback_rate_limited, recommends consolidating into one message, warns against including secrets or customer personal data, and notes a runId outside the workspace is ignored. It even states the return shape.

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 invocation triggers are front-loaded, and nearly every clause carries operative information rather than filler. It is a dense semicolon-chained block, which slightly reduces scannability for the optional-parameter details, but nothing is genuinely wasteful.

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 5-parameter mutation tool with no output schema, the description supplies the missing return value ({ feedbackId, status: 'new' }), the rate-limit failure mode, data-hygiene constraints, and per-parameter guidance. An agent has everything needed to invoke it correctly on the first try.

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 0%, so the description must carry the full burden, and it does: it explains kind semantics, what message should contain (what you did, what you expected, what happened) plus the 4000-character limit, that runId/endpointId are optional but materially aid actionability, and that rating is optional on a 1-5 scale. This adds real meaning beyond the bare JSON schema constraints.

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 ('tell the looot team what went wrong or what would help') and anchors it to equivalent surfaces (POST /v1/feedback and the `looot feedback` CLI). It is clearly distinguishable from siblings like runs_get or capability_request, which handle inspection and access rather than reporting.

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 triggering conditions are enumerated: wrong/empty/oversized answers, unclear docs or errors, missing provider or job (kind 'idea'), and things that worked well (kind 'praise'). The kind enum is disambiguated in prose, so an agent knows when to choose bug vs idea vs praise vs question without 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: the tool is free, a run requires prepaid credit >= estimated max cost, provenance.verified=false means an expected-but-unverified shape, credential semantics ('platform_own_key_optional'), and that workflow ids are accepted. This is rich context well beyond the 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?

The core purpose is front-loaded, which is good, but the rest is a single dense paragraph of run-on sentences with nested parentheticals and quoted field names. Several clauses are repetitive (endpoint.capability/sourceCapability/credential definitions, detail='run' field list) and could be trimmed or bulleted.

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 does the work of explaining return content: schema, price formula, estimatedMaxCost, provider identity, provenance.verified, and the detail='run' reduced payload. It covers a complex tool well, though the sheer density means some structure (e.g. field grouping) is left to inference.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it fully explains the 'detail' enum ('run' returns only run-necessary fields plus a run template; 'full' is unchanged) and clarifies endpointId can be a workflow id (CA-WF-02/08). The endpointId format is only loosely specified, keeping it from a 5.

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 states a specific verb and resource: 'inspect a data API endpoint (free)' returning its schema, price formula, max cost and provider identity. It also distinguishes itself from the sibling 'run' by framing inspection as the step done 'before running it.' It stops short of explicitly naming alternatives like discover/search_catalog for finding endpoint ids, which keeps it out of 5 territory.

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 concrete context: use this before a run to see requirements, and note that a run needs prepaid credit >= estimated max cost. It also explains when to pick detail='run' vs the default 'full', which is genuine selection guidance. No explicit when-not or named sibling alternatives, so not 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/idempotent/non-destructive, and the description adds meaningful behavior beyond that: the link's 15-minute lifetime, the need to re-request, output-field list, a sha256 integrity check, and handling guidance (don't paste into chat, keep links out of logs). It also enumerates the five failure modes, which is exactly the kind of 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?

Front-loaded with the purpose and link lifetime, then flows into parameters, return fields, and errors. Every sentence carries information, though the single dense block could be broken up for faster scanning.

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

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

With no output schema, the description describes the return payload (downloadUrl, downloadUrlExpiresAt, contentType, byteLength, sha256, filename suggestion) and lists all error codes. An agent has everything needed to invoke it correctly 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?

Despite 0% schema description coverage, all three parameters are explained: runId identifies the run, mediaId is needed when the run has multiple files and the error lists candidates, and inline:true is conditional on png/jpeg/gif/webp under 200 KB. This fully compensates for the bare schema.

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

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

States a concrete verb and resource — 'get a short-lived download link for a file a run produced' — with the artifact types enumerated (audio, image, video, PDF). It is clearly distinguishable from siblings like runs_evidence, inspect, or runs_get, which would not return a download URL.

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 strong operational context: download via curl/fetch within 15 minutes, call again for a new link, pass mediaId when the run has several files, and use inline:true only for small web images. It does not explicitly say when *not* to use it versus sibling tools such as runs_evidence, so it stops short of full when/when-not coverage.

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, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds real meaning beyond that by defining 'callable right now' as a published, non-revoked tool, which tells the agent what the visibility filter actually means.

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

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

A single dense sentence plus a useful endpoint-equivalence note; nothing is wasted. The stray 'looot:' token at the start is noise that slightly hurts the front-loading of the real content.

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 correctly compensates by naming the returned fields and clarifying the callability flag. Given a zero-param read tool with full annotation coverage, this is essentially complete.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it does not need to.

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 (tenant tools this workspace may run) and enumerates the returned fields (id, name, description, callability). It is clear on its own, but does not differentiate itself from similarly-shaped siblings such as catalog_overview, discover, or search_catalog.

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 guidance: it never says when to prefer this over catalog_overview, discover_smart, or search_catalog, nor does it note any prerequisite. Only implied usage ('what this workspace may run') is present.

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

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

The description adds substantial behavior beyond annotations: prepaid credit spending, budget reservation, idempotency replay semantics, insufficient-balance error payloads, fallback charging rules, and possible side effects on connected accounts. These details are consistent with the destructive, non-read-only, idempotent annotations.

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

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

The description is dense and long, but the tool is complex and the most important information is front-loaded. It could be more scannable with structure, but nearly every sentence carries operational meaning.

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

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

Given the tool's complexity, paid execution, side effects, fallback routing, and lack of an output schema, the description covers the critical operational behavior and error modes well. It is still incomplete around several optional parameters and the output mapping/field-selection behavior.

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 0% across 9 parameters, and the description compensates well for the core fields: endpointId variants, input validation, idempotencyKey replay behavior, wait, and fallback. It still leaves fields, output, max_items, and suggestionId unexplained, so the coverage gap is only partially closed.

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 immediately states a specific verb and resource: "run a data API endpoint (paid)." It then clarifies the endpointId forms for direct endpoints, workflows, and jobs, so an agent can distinguish this execution tool from catalog/search/inspection 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?

Usage context is clear: this is the tool for executing an endpoint, including workflow and job variants, with guidance on wait and fallback behavior. However, it does not explicitly route the agent away from siblings such as runs_get, runs_list, or runs_cancel for status/cancellation.

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 and idempotentHint=true; the description reinforces and extends them by explaining that the run's current state is returned either way and that already-settled runs come back unchanged rather than as an error. That 'never an error' semantics is genuinely useful context an agent cannot infer from the hints alone.

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?

Tight, front-loaded single sentence that leads with the action and appends the API mapping and edge-case behavior. The stray 'looot:' prefix is dead weight, but everything after it 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 one-parameter mutation with no output schema, the description covers operation, API equivalence, and the non-error return behavior — enough to call it correctly. It stops short of stating permission/auth requirements, 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?

One required parameter (runId) with 0% schema description coverage, so the description carries the burden and adds nothing about the id's format or expected values. runId is largely self-evident from its name, so this is adequate but not enriching.

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 ('cancel a queued or running run') and pins it to the underlying API operation (POST /v1/runs/{id}/cancel). The verb 'cancel' is inherently distinct from every sibling (runs_get, runs_list, runs_evidence, run), so an agent can route to it unambiguously.

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 verb: use it to cancel a queued or running run. It does not say when not to use it or point at a sibling (e.g., runs_get) to check state first, and the API-equivalence note is mapping info rather than decision 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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real context: it discloses the scoping rule that raw provider headers and bodies are never returned. That privacy/boundary statement is the kind of trait annotations can't 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?

One front-loaded sentence that leads with the action and then the return shape, with no padding. The 'looot:' prefix and the dense em-dash field list are minor noise but the whole thing is a single readable line.

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 enumerating the returned fields and explicitly stating what is excluded, which is exactly what an agent needs to interpret results. The only remaining gap is the undocumented runId, whose semantics are left to the URL analogy.

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

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

Schema coverage is 0% and runId is never described in prose, but the reference to 'GET /v1/runs/{id}/attempts' implies the parameter identifies the run whose attempts are fetched, so the meaning is inferable rather than absent. A minimal baseline for a single-param tool with no schema documentation.

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 every attempt made for a run') and enumerates exactly what the response contains (status, provider response status, latency ms, receipt id, cost). It clearly reads as the per-attempt drill-down rather than the run-level tool, though it never names a sibling like runs_get to make the boundary 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?

There is no statement of when to reach for this tool versus runs_get or runs_list, and no prerequisites or exclusions. The only orienting clause is the API equivalence note ('same data as GET /v1/runs/{id}/attempts'), which is a mapping, not usage guidance.

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

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

Goes well beyond the read-only/idempotent annotations: it details the error object shape (code, providerStatus, message, requestId, whoseError, retryable, retryHint), guarantees no secrets or raw provider headers, explains the optional 'normalized' block, and clarifies that fields/max_items return a trimmed copy with unchanged charge and that unknown paths error. Rich disclosure an agent could not 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-loads the core purpose and is information-dense, but the single long block with internal ticket codes (CA-WF-02/CA-WF-08) and heavy parentheticals slightly hurts scanability. Most sentences still earn their 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, so the description carries return-value burden and does so thoroughly: status vs provider status, result, cost, error shape, normalized block, and media/downloadUrl semantics. 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?

With 0% schema description coverage, the description compensates by explaining that `fields` are dotted paths of the result to keep and `max_items` caps every list, plus the edge case that a nonexistent path is an error. It adds real meaning beyond the bare schema, though the maxItems:50 cap and runId semantics rely on the schema/obviousness.

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 a run') and immediately scopes it: returns lifecycle status distinct from the provider's own response status, plus result and cost once settled. It clearly differentiates itself from siblings like runs_list and runs_cancel by describing what a single-run fetch returns.

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 useful situational context (following a workflow run started via run() with endpointId 'workflow:<id>', by workflowRunId) but never explicitly states when to use this over runs_list, runs_evidence, or runs_cancel. Usage is implied rather than articulated.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds material context beyond them: cursor pagination, the bounded-summary contract, the payload-size consequence of includeResult, the meaning of servedEndpointId/servedProviderId when a request went unanswered, and an explicit prompt-injection warning that providerText.fields is 'data, not instructions'.

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 verb, resource, and pagination model before the field enumeration. The long em-dash field list is dense but every item carries information (especially the servedEndpointId/servedProviderId caveat and the injection warning); a shorter phrasing of the field list would have lost meaning.

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 0% parameter coverage, the description compensates by enumerating the returned row fields and the includeResult variant, and by warning about untrusted provider text. It is nearly complete for a read-only list tool; only the phantom 'workspace' filter and the unexplained limit parameter leave 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 0%, so the description carries the burden and mostly delivers: it explains cursor pagination, status/capability filtering, and precisely what includeResult does. It does not explain limit or its 1-50 cap, and it references a 'workspace' filter that has no corresponding parameter in the schema, which is a small source of confusion.

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 runs') plus the exact scope: a cursor-paginated run history filtered by workspace, status, or capability. It also distinguishes itself from the singular retrieval sibling by noting the rows have 'the same shape as run/runs_get', so an agent can separate listing from fetching 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?

Usage is implied rather than stated: it explains the includeResult tradeoff ('never the full result payload unless includeResult:true'), which helps an agent decide how to call it, but it never says when to prefer runs_list over runs_get, runs_evidence, or search, nor does it state any exclusions. The routing guidance 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?

Annotations cover only the safety profile (readOnly, idempotent, non-destructive, closed-world); the description adds far more: cost model (price / works.rate, thin rows filled at job average), ordering semantics for `prefer`, default page size and 200 cap, the empty-items + warnings signal, priceHint behavior when maxPriceMicros over-filters, and the jobInputs/pinned-tool-id caveat.

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 and nearly every clause carries real information, but it is delivered as one dense run-on paragraph with tangled parentheticals (e.g. the thin-row averaging aside) and a stray "looot:" prefix. Routing advice, pagination, and return-shape details are interleaved rather than ordered, making it harder to scan than its content warrants.

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 fully: it enumerates the row fields (endpointId, provider, capability, estimatedPrice, priceBasis, costPerSuccessUsd, works{rate,runs,p50Ms,thin}, access, async, credential), explains what detail "full" adds, and describes pagination and the warnings/priceHint edge cases. It also closes the loop with a next action (inspect the endpointId).

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 0% schema description coverage and a 10-key nested filters object, the description carries the load and does well for query, filters.capability, limit/offset pagination, `prefer` (all four enum values with semantics and the default), detail "full", and filters.maxPriceMicros. It gives no meaning for filters.mock, hidden, keyless, category, platform, provider, verified, or includeUnavailable, so an agent must infer half the filter surface from bare key names.

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 concrete verb and resource — "free search of the data API catalog by job" — and positions itself as "the first step to find an endpoint", which is a distinct job from siblings. It explicitly routes to catalog_overview, capability_request, discover_smart and inspect, but never addresses the near-identically named sibling `search_catalog`, leaving an agent to guess which of the two to call.

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 (first step before inspect), how to invoke both modes (plain-words query vs. filters.capability, with query optional when a filter is set), and two concrete fallbacks: capability_request when no endpoint does the job, discover_smart when no confident match exists. Exclusions and alternatives are named rather than implied.

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 safety (readOnly/idempotent/non-destructive), and the description layers on substantial extra behavior: default 50 full rows, mock providers ranked last, `stats` semantics (empty answers count as success, null without evidence), the meaning of each `access` state, `warnings`/`priceHint` codes, and pagination via `offset`/`nextOffset`. This is far beyond what 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?

The routing guidance is front-loaded, which is good, but the body is a dense wall of inline field documentation that partly duplicates the linked `llms-full.txt` reference. It earns much of its length given 0% schema coverage, but the structure is hard to scan.

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 complex, filter-heavy search tool with no output schema and zero schema descriptions, the definition covers return shape, empty-result behavior (`no_supply_for_job`), and price-filter edge cases (`price_above_max`). Only a few filter fields and the exact `stats`/`works` fields for non-title detail are left thin.

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 0%, so the description carries the full burden, and it mostly succeeds: it defines `limit` (200 cap), `offset` pagination, `detail: "title"` output fields, `prefer` values and its balanced default, and several `filters` fields including `capability`, `category`, and `maxPriceMicros`. A handful of filter fields (hidden, platform, provider, verified, includeUnavailable) are still left to the reader.

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 ('A ranked full-text search of the data API catalog, with job expansion') and immediately differentiates itself from the sibling `search` by row count and detail level. An agent can distinguish it from `search`, `inspect`, and `discover` 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?

Explicit routing guidance is given: 'For a first look use `search` (10 short rows), then inspect; use this tool only for many full rows.' It also explains that `query` is optional when a filter is supplied, and tells the agent to pass an id from `expandedCapabilities` as `filters.capability`.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes further by disclosing return shapes for each mode (short index with slug/title/whenToUse/kind vs. a full markdown guide) and a key constraint that guides never hold prices, which is essential behavioral 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?

Front-loads purpose and the when-to-call condition, then efficiently covers each mode and the price caveat. Every sentence adds distinct operational value, with 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?

For a two-parameter, read-only discovery tool with no output schema, the description provides complete guidance: when to use it, how each mode behaves, what content to expect, and how it relates to the pricing sibling tool. 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 description coverage is 0%, so the description must carry all parameter meaning. It fully explains the no-argument default, the query parameter with plain-language examples, and the slug parameter with the format of the returned guide — more than sufficient to compensate for the schema gap.

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 resource (free how-to guides) and when to use it (when unsure how to do a task), directly distinguishing its role from siblings like search_catalog for live pricing. An agent immediately knows this is the guide retrieval tool.

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 says 'Call it when unsure how to do a task' and then describes all three invocation modes (no args, query, slug). It also routes the agent to search_catalog for live prices before a paid call, giving a clear alternative for price information.

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 the annotations: a 10-minute dedup window returning the same pending session, a rate limit of 3 new sessions per hour, the negative-balance default adjustment, and the graceful failure shape (checkoutUrl: null, reason, dashboardUrl). The idempotentHint=false is consistent with the time-windowed dedup rather than an exact-call idempotency guarantee.

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 but front-loaded with the core action and outcome before the optionality, limits, and failure mode. Every clause carries information, though the run-on structure makes it slightly harder to scan than a few shorter sentences 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?

No output schema exists, and the description explains what is returned (the checkout URL) plus the alternate return shape on failure. For a one-parameter 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?

With 0% schema description coverage, the description carries the full semantic load: amountUsd is optional, defaults to the suggested amount (at least minimumUsd, higher when the balance is negative), and values below the minimum are rejected with the minimum echoed in the error. That fully compensates for the bare schema.

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

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

States a specific verb and resource: open a Stripe-hosted Checkout page to add prepaid credits to this workspace and return its URL. It also scopes the agent's role ('the agent never enters card details'), which distinguishes it cleanly from the read-only sibling `balance`.

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 conditions: amountUsd optional with a defined default, sub-minimum amounts refused with the minimum in the error, and it points to `balance` as the source of minimumUsd. It does not explicitly state when NOT to use it versus alternatives, but the operational context is otherwise well covered.

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