CacheBoost

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

With no annotations, the description carries the burden and does disclose the runs:read authorization scope and the nature of the returned data (completion status, cache-hit counts). It doesn't cover error behavior for invalid/missing run IDs, so not 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?

Two tight sentences, zero padding, with the primary purpose front-loaded and the usage hint plus scope requirement following in a natural order.

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

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

For a single-parameter read tool with no output schema, the description covers purpose, trigger condition, and auth scope adequately. It stops short of describing possible status values or the shape of the cache statistics, which would have made it fully self-contained.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents run_id fully. The description adds no format or constraint detail beyond that, which is the expected baseline.

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

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

States a specific verb and resource ('Get the detailed status and cache-hit statistics of a single run'), and the singular 'single run' plus the required run_id cleanly distinguishes it from the sibling list_runs/get_site tools.

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

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

Gives a clear use case: checking whether a run created by warm_site has completed and how many URLs were cache-served. It does not explicitly name list_runs as the alternative for enumerating runs, so it falls short of the top-band when/when-not framing.

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 annotations, the description carries the full load and does a good job: it discloses the required sites:read scope and, notably, that a site outside the key's allowed site_ids is reported as not found rather than as an authorization error. It stops short of describing the response shape (error vs null) or any rate/caching behavior.

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

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

Three tight clauses, no repetition, and the core action plus returned fields are front-loaded before the scope and error behavior. 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 one-parameter, no-output-schema tool, the description covers the auth requirement, the returned fields, and the not-found masking behavior. The only small gap is not clarifying whether the not-found case raises an error or yields an empty 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% and the single site_id parameter is fully documented in the schema, including the ownership constraint. The description adds only the phrase 'by id', so the baseline 3 for schema-driven parameters applies.

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

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

States a specific verb and resource ('Get one site by id') and immediately narrows scope by enumerating the returned fields. The word 'one' cleanly separates it from the sibling list_sites, so an agent can route between them 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 by the required id and the singleton framing, but the description never explicitly says when to prefer this over list_sites or get_run. No exclusions or alternatives are named, leaving the routing inference to the agent.

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 annotations, the description carries the full burden but does well: it discloses the return ordering ('most recent first'), the cross-site scope, and the required auth scope ('runs:read'). It does not explicitly state read-only semantics or pagination boundaries, but the operation is transparently non-mutating.

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

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

Three sentences, each earning its place: capability, filtering/pagination, and routing guidance. The primary purpose is front-loaded with zero preamble.

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 tells the agent what kind of result to expect (run history, newest-first) plus the required scope. It stops short of describing the fields of a run record, which leaves a minor gap for a list tool.

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

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

Schema description coverage is 100%, so limit, offset, site_id, and boost_id are already documented. The description restates their roles (filter vs paginate) but adds no format, default, or constraint detail beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource ('List boost runs'), the scope ('across all of the key's sites'), and the ordering ('most recent first'). It is immediately distinguishable from get_run, list_warm_runs, and list_sites.

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 frames this as 'the history view' and routes the agent: 'to follow a run you just created with warm_site, prefer list_warm_runs or get_run.' This names both alternatives and the condition that selects them.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the auth requirement (sites:read), the ordering (most recent first), the completeness of the result set, and the absence of pagination — all non-obvious operational traits. It could go further on error behavior or empty-result handling, but the essentials are covered.

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

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

Three compact sentences, each earning its place: purpose, prerequisite scope, and the no-argument/no-pagination constraint. Everything is front-loaded 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?

There is no output schema, so the description usefully states what is returned (all authorized sites, most recent first). It is nearly complete for a zero-param list tool; only the shape of a site object is left unspecified, which is a minor gap.

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

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

Zero parameters, so the baseline is 4. The description reinforces this with 'Takes no arguments', leaving no ambiguity for the agent.

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 gives a specific verb (List) and resource (sites) with scope (accessible to the API key), which cleanly separates it from the singular get_site sibling. It stops short of explicitly naming alternatives, but the plural/scope framing makes the distinction inferable.

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 states the required scope (sites:read) and that no filtering or arguments are involved, giving the agent clear context for when this tool applies. It doesn't explicitly state when NOT to use it or point at a sibling, so it falls 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?

No annotations are present, so the description carries the full behavioral burden. It does add useful non-schema context — the required 'boosts:read' scope and the most-recent-first ordering. However it does not describe retention, what a 'run status' can be, or pagination/failure behavior, leaving gaps for a polling 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 sentence that front-loads the verb, resource, ordering, and purpose with zero filler. Every clause earns its place.

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

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

For a simple read-only list with a fully documented schema, the description covers purpose, ordering, use case, and auth scope. With no output schema, it only loosely signals the return ('their status'), which is a minor gap but not blocking.

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% (limit, offset, site_id all documented in the schema), so the baseline is 3. The description adds no parameter-level detail beyond what the schema already provides.

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

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

States a specific verb and resource ('List the inline warm runs of a site'), plus the ordering (most recent first) and the downstream purpose (polling after warm_site). The qualifier 'warm' and the reference to warm_site distinguish it from the sibling list_runs, though the contrast is implicit rather than stated.

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 frames the use case: poll warm run status after calling warm_site. That gives a clear when-to-use context. It stops short of naming alternatives (e.g., list_runs) or stating when not to use it.

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

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

With no annotations, the description carries full behavioral burden and does so: asynchronous execution ('takes seconds to minutes depending on the URL count'), the return value (run_id), the per-site concurrency constraint, and the required authorization scope (boosts:write). This is exactly the 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?

Four short sentences, front-loaded with the core action and outcome, followed by asynchrony guidance, concurrency constraint, and auth requirement. No filler or redundancy.

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

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

For an async mutation with no output schema, the description covers what is created, what is returned (run_id), how long it takes, how to poll results, the concurrency limit, and the required scope. 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 100% and all four parameters (site_id, urls, region, variations) are documented in the schema itself. The description adds only the 'same-origin' constraint and site ownership notion, which are already implied by the schema text, so baseline 3 applies.

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

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

States a specific verb and resource ('Warm (pre-cache) a list of same-origin URLs for one of your sites') and adds the concrete outcome ('Creates a warm run and returns its run_id'). An agent can distinguish it from list_warm_runs/get_run siblings purely from this text.

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 instructs to follow the call with list_warm_runs or get_run rather than assuming completion, and notes 'A site runs one warm at a time,' which tells the agent not to fire concurrent warms. It does not spell out when not to use this tool, 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?

No annotations are provided, so the description carries the full burden. It discloses that this is a read-only identity check (returns, no side effects implied), the exact fields returned, and that scope failures in other tools motivate calling it. It does not mention idempotency or rate limits, but those are minor for a zero-parameter identity probe.

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

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

Two tightly written sentences: the first front-loads purpose and return fields, the second gives usage guidance and rationale. No wasted words.

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

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

For a simple identity tool with no output schema and no annotations, the description fully compensates by listing return fields and explaining the call-first prerequisite. An agent has everything needed to invoke it correctly.

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

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

The tool has zero parameters, so the baseline of 4 applies. The description appropriately adds no parameter semantics since none exist.

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 'Returns' and the resource 'identity of the authenticated API key', and enumerates the exact fields returned (user_id, scopes, site_ids). This clearly distinguishes it from sibling tools that operate on runs or sites.

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 first when you do not know which sites the key reaches or which scopes it holds', giving both the condition and the reason ('every other tool fails on a missing scope'). This directly informs when to choose this tool over any sibling.

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