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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond them by decoding the fields returned, defining the credit unit (1 credit = $0.01) and explaining escrow/pending/holds/available, plus the zero-cost signal that no annotation conveys.

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 sentence, front-loaded with the resource being read, then a compact parenthetical that defines each sub-field. The parenthetical is dense but every clause maps to a returned value; only the terminal "Free." is slightly terse relative to its usefulness.

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

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

With no output schema, the description carries the burden of explaining returns, and it enumerates credits, unsettled debt, prepaid account and payment rail along with the four credit sub-buckets. It does not describe the response envelope, ordering, or units for debt/prepaid fields, a small residual gap for a zero-parameter 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 no parameters, so there is no per-argument semantics to explain and the baseline of 4 applies. The description does not waste words on arguments that do not 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?

"Spendable balance of the Carpe Diem account behind CARPE_API_KEY" names a concrete resource and the credential it belongs to, and it distinguishes the subject from usage-focused siblings like carpe_usage_summary or carpe_key_usage. It stops short of explicitly naming a sibling it replaces, so an agent must infer the balance-vs-usage split.

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

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

Usage is only implied: a spendable balance suggests a pre-flight check before paid calls, and the trailing "Free." signals it can be called without cost. There is no explicit when-to-use, no when-not-to-use, and no mention of when carpe_usage_history or carpe_session_spend would be the better call.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) the description discloses the paid nature, that the response includes usage, exact billed cost and serving market, that tool calls are returned rather than executed, that web search carries an extra flat fee, and the TEE/privacy difference between routes. That is exactly the behavioral context an agent needs before spending money on a non-idempotent call.

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 critical facts — what it is, the two routes, what comes back, cost warning — are front-loaded, and the model-list parenthetical is the only slightly bloated part. It stays dense but readable for a complex 18-parameter tool.

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

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

For an 18-parameter tool with nested objects and no output schema, the description does the important work: it describes the return payload (answer, usage, cost, market) and the two routing surfaces. Remaining gaps are standard LLM parameters (temperature, top_p, seed) that an agent will recognize from convention.

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 72%, so the schema already documents route, privacy, provider, max_tokens and others. The description still adds value by grouping the supported capabilities (function tools, response_format JSON schema, reasoning_effort, Venice web search) and flagging the per-search fee, though it says nothing about seed, stop, top_p, temperature or the precedence rules already encoded in the schema.

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

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

The description opens with a specific verb+resource ("Run a chat completion on Carpe Diem") and immediately differentiates it from siblings like carpe_embeddings, carpe_web_search and the image/video/audio generators by naming the OpenAI-compatible surface and model families. The two-route explanation further pins down exactly what this call does that no other tool in the list does.

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 actionable routing guidance ("carpe" for private TEE, "router" for cheapest market) and an explicit cost-control alternative: "use carpe_quote first for expensive requests." What's missing is a when-not statement — nothing says when to prefer carpe_embeddings or a different tool, though the domain separation is fairly obvious.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, which are otherwise confusing for a 'compute' tool; the description supplies the missing reason — 'Paid per input token' — so the agent understands each call costs money and is not a free repeatable read. It also discloses that route 'carpe' is always served in a TEE while 'router' may be served outside one. It stops short of describing the response shape or batching 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 short sentences, front-loaded with the core action before the routing and cost caveats. Dense but readable; 'privacy applies' is terse to the point of being cryptic, costing a point.

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?

Covered: what it does, batch limit, cost model, routing/privacy trade-off. Missing for a 6-parameter tool with no output schema: any indication of what comes back (vector arrays, dimensions of the returned vectors, base64 encoding implications) and the default model behavior. Adequate but leaves real gaps.

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

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

Schema coverage is 67%, so a baseline 3 applies. The description restates what the schema already documents for `route` (carpe vs router, cheapest market) and the 1–128 input count, and adds nothing about `model`, `dimensions`, or `encoding_format`; the privacy semantics it gestures at ('privacy applies') are only spelled out in the schema.

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

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

States a specific verb and resource ('Compute embedding vectors') plus the compatibility contract (OpenAI-compatible) and the batch bound (1–128 texts). That is unambiguous and clearly separable from siblings like carpe_chat, carpe_tts, or carpe_list_models.

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 implied rather than stated: the agent can infer this is the text-to-vector tool and that 'router' is the cheapest option with privacy trade-offs. There is no explicit when-to-use/when-not guidance versus alternatives, and no pointer to carpe_list_models for discovering model ids (that hint lives only in the schema).

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the agent knows this is a non-idempotent external write. The description adds nothing beyond that: it does not disclose that requests may be queued for slow models, that a job_id may be returned instead of an image, or that 'route' controls a privacy trade-off. The only extra content is accepted image input forms, which the schema's 'image' description already states verbatim.

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 short sentences, front-loaded with the action and followed by the input constraint; nothing is padded. The second sentence largely restates the schema's 'image' description, which is the main wasted 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?

For a 12-parameter, paid, potentially queued image-editing call with no output schema, the description omits the async/job_id path, cost and routing implications, and half the parameters. An agent could call it, but cannot predict latency, spend, or what a queued response looks like from this text alone.

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

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

Schema coverage is 50% across 12 parameters, with six (format, quality, safe_mode, resolution, aspect_ratio, prompt) undocumented. The description lists example imageEdit model ids, which adds a little meaning to 'model' beyond the schema's default-plus-pointer, but it says nothing about the undocumented knobs or about mode/wait_seconds queue behavior, so it only partially compensates for the coverage 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?

The description names a specific verb and resource ('Transform one image from a prompt') and gives concrete model examples (qwen-image-2-edit, nano-banana-2-edit, gpt-image-2-edit) that identify the model class in play. The phrase 'one image' implicitly separates it from carpe_image_multi_edit, but no sibling is named explicitly, so an agent must infer the boundary rather than read it.

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

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

There is no statement of when to choose this over carpe_image_generate, carpe_image_multi_edit, or carpe_image_upscale, and no prerequisites or exclusions. The only routing hint is the word 'one', which is inference, 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 already declare openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the description's value is in the extra detail it supplies: fixed per-image pricing, images returned inline and/or written to CARPE_OUTPUT_DIR, and automatic queuing of slow models. The async disclosure is the most important addition, though it omits how to follow up on a returned job_id.

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, front-loaded with the core action and followed by output location, cost, and queuing behavior in descending order of importance. The model-list parenthetical is dense but earns its place by signaling capability breadth.

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 16-parameter generation tool with no output schema, the description correctly covers the return channel and the queue path. The key gap is that it mentions a job_id being returned after wait_seconds without telling the agent to poll carpe_image_status, leaving the async workflow incomplete.

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

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

With 16 parameters and 69% schema description coverage, the schema already documents the important knobs (mode, model, route, format, quality, variants, safe_mode, resolution, aspect_ratio, wait_seconds, extra). The description adds only marginal meaning — default model families, default tiering behavior, pricing implications — and says nothing about the undocumented prompt, seed, width, height, or negative_prompt params.

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 ("Generate image(s) from a prompt") and enumerates the serving model families, so an agent immediately knows this is text-to-image creation rather than editing or upscaling. Sibling tools like carpe_image_edit and carpe_image_upscale are not named explicitly, but the verb distinction is strong enough to disambiguate.

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

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

The description routes the agent usefully in two places: it points to carpe_pricing for cost and to carpe_list_models for model ids, and it explains that slow models are auto-queued. However, it never states when to prefer this over carpe_image_edit, carpe_image_multi_edit, or carpe_image_upscale, and gives no when-not-to-use conditions.

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 non-readOnly, non-destructive, open-world, non-idempotent, so the mutation profile is known. The description adds genuinely new behavior — 'Runs as a queued job' — which explains why wait_seconds exists and implies a job_id return path, but it stays silent on cost, timeout behavior, and how to retrieve a job that outlives the wait.

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 what the tool does and immediately followed by a concrete usage example and the routing caveat. Every sentence adds information; only the '/v1' phrasing is slightly jargon-heavy.

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 10-parameter, nested-object, async image mutation with no output schema, the definition covers the core intent but leaves the agent guessing on return shape (image URL vs job_id), polling via carpe_image_status, and the semantics of most optional parameters. Adequate to start a call, not complete enough to use it confidently.

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 only 40% across 10 parameters, so the description needs to compensate and largely does not. It touches prompt and the 1–3 images constraint and hints that wait_seconds relates to the queued job, but model, quality, resolution, aspect_ratio, safe_mode, output_format, and the passthrough 'extra' object get no explanation.

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 plus resource ('Compose or edit') and constrains the input to '1–3 source images and a prompt', which is what separates it from the single-image carpe_image_edit sibling. It never names that sibling, but the arity constraint alone lets an agent pick correctly.

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 only routing guidance is 'Always on /v1 — no market arbitrates multi-edit', which tells the agent not to worry about market selection but not when to choose this tool over carpe_image_edit, carpe_image_generate, or carpe_image_upscale. There are no exclusions and no prerequisites stated.

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

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

Annotations already cover idempotency, open-world, and destructiveness, so the bar is lower. The description contributes two genuinely non-structured facts: polling is scoped to the surface that created the job, and the call is free. It does not explain why readOnlyHint is false — presumably retrieving consumes the job — nor what remains after a poll, which is the main behavioral unknown left.

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 clauses, front-loaded with what the tool returns, then provenance, then cost. No filler. The 'Free.' fragment is terse but earns its place as cost information the schema does not carry.

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?

Only two parameters, no nested objects, and annotations are present, so the definition is close to sufficient. The significant remaining gap is that there is no output schema and the description never says what a successful fetch returns (URL, base64, status field) or what an incomplete job yields — information the agent needs to handle the response.

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 50%: wait_seconds is fully documented in the schema, while job_id has no schema description. The description partially compensates by stating that job_id comes from an image tool, but says nothing about its format or about wait_seconds behavior (blocking vs returning). Marginal value over the schema.

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

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

States a specific verb and resource: 'Fetch the result of a queued image job.' The parenthetical '(job_id from an image tool)' scopes it to image jobs, which implicitly separates it from carpe_video_status and carpe_music_status without naming them. Clear enough to select, though the sibling differentiation is by implication rather than explicit contrast.

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 tells the agent where the job_id comes from ('from an image tool'), which implies the tool is used after carpe_image_generate/edit/upscale. But there is no explicit when-to-use, no guidance on polling cadence or when to stop, and no statement about what to do if the job is still queued. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true. The description adds genuine context beyond them: the fixed /v1 endpoint, the minimum source size, and the accepted input transports including stdio local paths. It does not say whether the job is synchronous or requires polling carpe_image_status, nor what the output looks like, which is a meaningful gap given 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?

Three terse fragments, front-loaded with the operation and scale range, with zero filler. The telegraphic style ("/v1.", "(stdio)") is efficient but slightly cryptic for a first-time reader.

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 4-parameter, open-world mutating tool with no output schema, the description covers input adequacy well but leaves the response unexplained (upscaled image URL vs. base64 vs. job ID) and never mentions async/status polling despite carpe_image_status being a sibling. An agent could invoke it correctly but may not know how to retrieve or 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 75% and the undescribed parameter is exactly `image`, which the description clarifies (https URL, data: URI, or local path over stdio). It also restates the 1–4 scale bound with the source-size floor, adding a real constraint. This is meaningfully above the schema-only 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?

"Increase image resolution 1–4×" names a specific verb (increase resolution) and resource (image) with a quantified output range, which is clearly distinct from sibling generators like carpe_image_generate or carpe_image_edit. It does not explicitly name those siblings or state the boundary, so it stops short of a 5.

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

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

The source constraint ">= 256×256" implies when the tool is applicable and implies the input must already be an existing image (vs. generation). However, there is no explicit statement of when to use this versus carpe_image_edit / carpe_image_multi_edit, and no mention of alternatives for sources below the size floor.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful context by listing the metrics returned and noting that the call is free, but it does not mention authentication requirements, pagination, or response format details.

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

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

The description is a single efficient sentence with the scope, metrics, and cost note front-loaded. Every phrase adds information, and there is no unnecessary wording.

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 tool with one optional parameter and no output schema, the description is nearly complete: it explains the grouping, time window, returned metrics, and free status. The main omission is the default lookback behavior when days is not supplied.

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

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

The schema has one optional parameter, days, with 0% description coverage. The description says 'over the last N days,' which gives the parameter meaning, but it does not state the default when days is omitted, so it only partially compensates 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?

The description clearly states what is returned: requests, tokens, cost, rail, and status per API key over the last N days. It is specific enough to distinguish this from generic account-level usage, but it does not explicitly contrast itself with sibling tools such as carpe_usage_summary or carpe_usage_history.

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

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

There is no explicit guidance on when to use this tool versus the many sibling usage and billing tools. The word 'Free' is a useful cost signal, but it does not tell the agent when this per-key view is preferable to carpe_usage_summary or carpe_usage_history.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the catalogue is live, it is free, results are paged, and route='router' reads a different endpoint (/router/models) that augments text models with best-price markets. It still omits pagination mechanics and what a result row contains.

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 filters, then the routing map — a sensible information hierarchy with no filler sentences. The routing list is long and partly duplicates the route parameter's schema description, so it is dense rather than perfectly lean, but every clause carries actionable 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?

For an 8-parameter tool with no output schema, the definition should give some sense of what a returned model record looks like; it only hints via 'verbose' returning full rows versus summaries. Safety, scope, cost and downstream routing are all well covered, so this is a solid but not complete picture.

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 88%, so the baseline is 3, but the description adds the semantic distinction that route='router' attaches best-price markets per text model, which clarifies a parameter whose meaning is otherwise opaque from the enum alone. It also frames capability and privacy as filters over catalogue rows rather than raw flags.

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?

Uses a specific verb and resource ('Page through the live Carpe Diem model catalogue') and immediately scopes it as 'Venice models plus Carpe metadata', which separates it from siblings like carpe_model_details and carpe_pricing. The filtering axes (type, capability, privacy, search) further pin down exactly what this tool does.

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

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

Provides an unusually explicit routing table mapping each carpe_diem_type value to the correct downstream action tool (text → carpe_chat, tts → carpe_tts, etc.), so an agent knows what to do after listing. It does not, however, say when to prefer this list over carpe_model_details, carpe_markets or carpe_pricing, which remain plausible alternatives for model 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so safety is covered elsewhere. The description's real additions are the disclosure that the data is live/observed rather than cached and that the call is "Free" — useful cost context — but it says nothing about freshness windows, snapshot staleness, or response shape beyond the field list.

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 sentence front-loads the resource, then a comma list of returned fields, closed by the cost signal "Free." There is no filler, no restatement of the title, and the most decision-relevant information (what you get, at no cost) arrives first.

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 burden of describing the return payload, and it does so by naming all four categories of data. A short note on response format or refresh cadence would close the remaining gap, but an agent can call this correctly with what is present.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The enumeration of returned fields does not need to double as parameter documentation here.

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 and surface: the live state of /router best-price markets, then enumerates the exact facts returned (enabled markets, external routing fee, per-market latency, external-execution permission for the key). That is far more specific than a tautology, but it never names a sibling such as carpe_routing_summary or carpe_status, so an agent must infer the boundary itself.

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?

"Live state" plus "whether external execution is open to this key" implies the use case: checking current market availability and permission before routing. There is no explicit when-not guidance and no named alternative (e.g., routing summary vs. per-market latency), so selection against siblings remains implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral context beyond them: the call is free and it returns live capacity and rate limits, which tells the agent this is a cheap, safe call that can be made liberally. It stops short of describing response shape or whether capacity figures are real-time snapshots.

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 opening with 'Everything about one model:' followed by a compact enumeration of returned fields. It is dense with parentheticals but every clause adds information and there is no filler; a light restructure of the nested parentheses would make it a 5.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by listing the field groups an agent will receive. Combined with read-only annotations and a fully documented single parameter, an agent has enough to call it correctly; only the response format (object shape, units) is left unstated.

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

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

Schema coverage is 100% and the single parameter already documents that an exact model id is required. The description reinforces the one-model-per-call framing but adds no format, casing, or aliasing details beyond the schema, 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?

The description states a specific resource (one model) and enumerates the payload precisely: catalogue row with capabilities and constraints (video durations, music lengths, TTS voices), Carpe price, Venice rate limits and live capacity. That is far more informative than a tautology, though it never names the sibling it replaces (carpe_list_models for discovery, carpe_pricing for cross-model price comparison).

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

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

Usage is only implied: an agent can infer this is the single-model lookup while carpe_list_models is the multi-model list, but the description does not say when to prefer this over carpe_pricing or carpe_rate_limits, nor any prerequisites. The 'e.g. from carpe_list_models' hint lives in the schema, not the description, so the discovery-to-detail flow is left implicit.

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

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

The annotations already declare non-read-only, non-idempotent, open-world, non-destructive behavior, so the description's main added value is disclosing the async job model and the job_id return. It also warns that durations, lyrics, and instrumental support vary by model, which is genuinely useful behavioral context. It omits any mention of credit cost or billing consequences for a paid generation call, which is the most important missing behavior for an agent deciding whether to invoke it.

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

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

Three sentences, front-loaded with the verb and resource, then prerequisites, then the return value. The parenthetical model list is dense but earns its place by signaling which backends are in play. Minor waste in restating the force_instrumental constraint already present in the schema.

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

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

For a 10-parameter, no-output-schema generation tool, the description covers the essentials: what it produces, that it is async, the job_id return, and where to find model constraints. It falls short on cost/credit implications and on the meaning of several optional parameters, but the core call-and-poll contract is 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?

With only 50% schema description coverage across 10 parameters, the description partially compensates by explaining that durations, lyrics, and instrumental options are model-dependent and must be checked via carpe_model_details. However, voice, speed, extra, and lyrics_prompt receive no semantic explanation in either place, and the nested 'extra' object is entirely opaque. The guidance adds real meaning for a few parameters but does not close the coverage 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?

The description uses a specific verb ("Queue") and names the concrete resources produced: music, sound effects, and long-form speech, plus the model families involved. An agent can immediately tell this is an asynchronous generation endpoint rather than a status, listing, or pricing tool. It does not, however, disambiguate itself from the sibling carpe_tts even though it explicitly claims TTS v3-v4 coverage, which leaves a real overlap for the agent to resolve.

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 workflow guidance: read per-model constraints via carpe_model_details first, and poll results with carpe_music_status. That is a clear prerequisite-and-follow-up chain rather than implied usage. What is missing is any when-not guidance, particularly when to prefer carpe_tts over this tool for speech, or when the router route should be chosen over carpe.

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 signal that this is not a pure read (readOnlyHint=false) and is otherwise safe; the description supplies the materially important behavior: the file is written to disk and can be retrieved only once on /v1, so a missed retrieval is unrecoverable, and the call is free. That one-time-retrieval warning is exactly the kind of context annotations cannot express, though the tension with idempotentHint=true for the download path is left unexplained.

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 no filler, front-loaded with the action and ending with the cost note. Every clause (source tool, disk save, one-time retrieval, free) carries decision-relevant 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 two-parameter tool with no output schema, the description covers what triggers it, what it returns, the one-shot retrieval constraint, and pricing. It leaves out failure/timeout behavior and what a call returns before completion, but the wait_seconds schema note partially fills that gap.

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

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

Schema coverage is 50%: wait_seconds is fully documented in the schema, but job_id has no schema description. The description partially compensates by telling the agent job_id comes from carpe_music_generate, but adds nothing about format, reuse, or post-completion behavior of that id.

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 a music job") and explicitly ties the job to its producer, carpe_music_generate, which distinguishes it from the image/video status siblings without opening any schema. It also states the outcome at completion (track saved to disk and returned).

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 usage context is unambiguous: call this after carpe_music_generate, and the wait_seconds schema note tells the agent to poll later with the status tool for longer jobs. It doesn't state an explicit when-not or name a fallback sibling for job tracking, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine value by saying prices are 'live' and by defining the price fields (inputPrice/outputPrice are post-multiplier, inputBase/outputBase are Venice list prices) and that media pricing is a fixed per-call USD figure. That field semantics is useful context, though it edges into return-value territory rather than behavior of the call itself.

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, front-loaded fragments with no filler: what it returns, how token prices are expressed, how media prices are expressed, and how to filter. The telegraphic style ('Free.') is efficient for an agent reader, though the fragment structure makes the field-semantics sentence dense on first read.

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

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

With no output schema, the description carries the burden of explaining return values and does so for the price fields, which is the most important missing piece. The remaining gaps are the undocumented sort enum and the shape of a media row. For a four-parameter read-only lookup these are minor, and the annotation coverage plus field definitions make it callable without guessing.

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 75%: kind and limit carry descriptions, model is covered, and only sort is undocumented in both places. The description repeats the model-substring filter and adds no syntax or default details for sort, so it does not compensate for the one gap. Baseline 3 is appropriate given the schema does most of the work.

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

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

States a specific resource (live Carpe prices) and immediately splits it into two priced categories, token models vs media, which tells an agent exactly what data comes back. It does not name the nearest siblings (carpe_model_details, carpe_quote, carpe_markets), so differentiation is left implicit, but the 'prices' framing is clear enough to distinguish it from a catalog or quote 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?

There is no explicit when-to-use guidance and no mention of alternatives such as carpe_model_details for a single model or carpe_quote for a cost estimate. The only procedural hint is 'Filter by model substring', which is a parameter behavior rather than a usage rule. An agent must infer the routing decision from the tool name alone.

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, non-destructive, and closed-world, so the safety profile is covered. The description's only addition is "Free," which usefully signals no billing impact, but it says nothing about what is returned, how purchases are ordered or paginated, or the scope of the account data. Minimal value beyond the annotations.

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

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

It is short with no wasted words, but the size comes from under-specification rather than tight writing, and the fragmentary phrasing plus the dangling "Free." makes it feel clipped rather than front-loaded.

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

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

With no output schema and no return-value discussion, an agent cannot tell what calling this yields — a transaction list, a count, or a total. For a zero-parameter read tool the description should at least state the shape of 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The empty schema makes the parameter story 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?

"Credit purchases made by card on the account" identifies the resource being described, but it is a sentence fragment with no verb, so it is ambiguous whether the tool lists, summarizes, or looks up purchases. It also does not distinguish itself from sibling history tools like carpe_usage_history, carpe_session_spend, or carpe_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?

There is no when-to-use guidance at all: nothing tells the agent when to pick this over the many other account/history siblings. The word "Free" faintly implies a zero-cost alternative but is not framed as a routing rule.

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

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

Annotations already establish a safe, idempotent, closed-world read, so the bar is lower; the description still adds real value by disclosing that the result compares two surfaces and enumerates each market's price, availability, and TEE status. It could have said more about how the input-size estimate is derived or what happens when a model is unknown.

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

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

Two compact sentences with zero filler, and the core promise ('Price... BEFORE running it') is front-loaded before the optional inputs are described. The /v1 and /router jargon is dense but each term is immediately glossed.

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

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

With no output schema, the description carries the burden of describing the response, and it does outline the comparison plus per-market price, availability, and TEE flag. Edge cases such as unknown models or empty estimates are not covered, which keeps it just short of complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond per-field docs by explaining the relationship between the inputs: messages or prompt drive the input-token estimate, while input_tokens overrides it outright. That mutual-exclusivity guidance is genuinely additive rather than a restatement of 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 ('Price a text request') and scopes it precisely: it reports what /v1 alone would bill and what /router would pick across markets. That is clearly distinguishable from siblings like carpe_chat (which executes) and carpe_pricing/carpe_markets (which expose static price/market data).

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

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

The phrase 'BEFORE running it' tells the agent this is the pre-flight step ahead of carpe_chat, and 'Costs nothing' removes any hesitation about calling it. It stops short of explicitly naming the alternatives to use when the user only wants static pricing or market lists.

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

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

The annotations already establish that this is a safe, read-only, idempotent operation. The description adds meaningful behavioral context beyond annotations by naming the returned rate-limit dimensions, separate read budget, parallel lanes, and that the call is free.

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

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

The description is a single compact sentence that front-loads the core purpose and then lists the returned categories. It is efficient, though slightly dense; it could be structured more readably without adding length.

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 burden of explaining what is returned. It does so by listing the key rate-limit dimensions and the separate read budget, though it does not specify exact response shape or units.

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?

This tool has zero input parameters, so there are no parameter semantics for the description to clarify. The baseline for a parameterless tool is 4, and nothing in the description creates confusion about inputs.

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

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

The description clearly identifies the resource as the operator rate limit applied to the current key, with specific fields such as max per window, remaining, reset, read budget, and parallel lanes. It is easy to distinguish from siblings like balance or usage history, though it does not explicitly name any alternative 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?

The description does not say when to use this tool versus alternatives or when not to use it. 'Right now' and 'Free' provide helpful context, but there is no explicit guidance such as checking limits before making calls or using a different sibling for spend/cost data.

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 beyond the annotations by spelling out consequences: the action is irreversible, the specific credential (CARPE_API_KEY) is destroyed, and every subsequent call with it fails. It also discloses the exact confirmation token required, which is the kind of safety-relevant behavior an agent needs before invoking a destructive 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?

Three short sentences with the most critical warning ('IRREVERSIBLE') front-loaded, followed by consequence, then authorization condition and input requirement. No filler and nothing buried.

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 destructive tool with no output schema, the description covers irreversibility, blast radius, authorization criteria, and the required confirmation value. An agent has everything needed to decide whether to call it and how.

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 'confirm' parameter is already constrained to the literal 'REVOKE' with its own description. The description repeats the required value, adding only the implication that the token is a deliberate-intent safeguard, which is marginal beyond the schema.

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

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

States a specific verb and resource ('permanently revokes the API key this server uses') and names the exact key variable CARPE_API_KEY, making it unmistakable among the many read/usage siblings. The '(kill switch)' framing in the title is reinforced in the description rather than merely restated.

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 gating condition: use only if the user explicitly asks or the key leaked. It does not name an alternative tool, but there is no sibling that performs revocation, so the guidance is functionally complete without a routing pointer.

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, so the safety profile is covered. The description adds the useful cost fact ("Free") and states the report's contents. It does not disclose the default lookback window when 'days' is omitted, which is meaningful behavior for a summary 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?

Two short sentences, front-loaded with the report's content, and the trailing "Free." carries real decision value at minimal cost. Nothing is redundant.

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 carry the burden of explaining returns, and it sketches them (wins per market, savings vs baseline pricing) without detail on shape. The missing default time window and lack of sibling differentiation leave it only minimally adequate for a free analytical report.

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% for the single 'days' parameter, and the description says nothing about it — no default value, no note that 1–90 is the permitted range, and no indication of what window is used when it is omitted. With only one parameter the description could easily have compensated, so the gap is a real one.

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 the specific resource and content: how /router requests were served, wins per market, and savings versus Carpe-only pricing. That is far more specific than the title alone. It does not distinguish itself from close siblings like carpe_usage_summary or carpe_pricing, so an agent must infer the boundary.

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

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

There is no explicit when-to-use guidance and no named alternative among the many usage/pricing siblings. The word "Free" hints that it is a zero-cost call, which is mild encouragement, but the agent is left to infer when this report is preferable to carpe_usage_summary or carpe_session_spend.

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, so the bar is lower. The description still adds real context: the measurement window is since server start, the breakdown is per tool, the values relate to two named guard variables, and 'Local, free' tells the agent the call costs nothing and makes no network request.

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 short sentences, zero filler, with the core scope (session spend, per tool) front-loaded before the guard context. The clipped 'Local, free.' fragment still earns its place by conveying cost and network behavior.

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 parameterless, read-only, locally computed status tool, the description covers scope, grouping, and the limits being compared against. It does not sketch the response shape (a per-tool map of dollar amounts), but with no output schema and a trivial input, that is a minor omission.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The schema is empty and 100% covered, so no compensation is needed.

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 resource and scope: spend accrued by this MCP server since it started, broken down per tool. It does not explicitly distinguish itself from near-siblings such as carpe_balance, carpe_usage_summary, or carpe_key_usage, so an agent must infer the difference from the word 'session'.

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

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

Usage is only implied: 'Local, free' signals this is a cheap call to check spend against the CARPE_MAX_SPEND_USD and CARPE_MAX_PER_CALL_USD guards, which hints at budget-checking use. There is no explicit when-to-use/when-not-to-use statement and no routing to alternative spend or usage tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact beyond the annotations — that the call is free — but says nothing about response shape, freshness of health data, or whether capacity figures are per-key or global.

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 telegraphic fragments, front-loaded with the primary payload (operator health) before the secondary one (marketplace capacity), with the cost note last. Every clause carries information; the fragment style is terse but not 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 zero-parameter, read-only status probe with no output schema, the description gives the agent enough to know what categories of information come back. The main remaining gap is the absence of any output structure hint (e.g., whether capacity is reported as a number, tier, or per-endpoint breakdown), which matters slightly more because no output schema exists.

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 and the schema is an empty object, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing parameter behavior.

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 resource (service status) and enumerates the data domains covered: operator health (database, settlement, providers) and marketplace capacity (headroom, price multiplier). This is far more concrete than a bare 'get status', though it never names which siblings (carpe_x402_status, carpe_rate_limits, carpe_balance) are the alternatives for adjacent questions.

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

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

There is no when-to-use or when-not-to-use guidance. It doesn't tell an agent whether to call this before a paid request to check capacity, or whether carpe_rate_limits or carpe_balance is the better fit for that question. The only implicit cue is the word 'status' in the title.

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 not read-only and not destructive; the description adds the crucial facts that no charge occurs, that a human must complete payment, that the URL is time-limited, and that the agent must not follow the link. That is exactly the behavioral context the annotations cannot convey.

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

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

Three tight clauses: what it is, what it does in each mode, and the safety prohibition. The most consequential constraint (nothing is charged; a human must pay) is front-loaded with zero 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-optional-parameter tool with no output schema, the description adequately covers both outcomes (URL vs tier list) and the human-in-the-loop requirement. Minor gaps remain: how long the link is valid and what the tier listing contains are unspecified, though neither blocks correct invocation.

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

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

Schema coverage is 100% and both parameters are already documented with defaults and examples, so the structured data does the heavy lifting. The description reinforces the meaning of create:true by describing the resulting behavior, but adds no new detail about tier_id or accepted values.

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?

"Card top-up for this account" names the verb and resource, and the description then splits the tool's two modes explicitly: with create:true it returns a checkout URL, otherwise it lists credit tiers. An agent can tell this apart from balance/usage/purchases siblings purely from the 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?

It gives a clear conditional for the two operating modes (create:true for a checkout link, default for tier listing) and an explicit agent-behavior rule: never open or pay the link yourself. It does not name a sibling alternative (e.g. carpe_balance) for checking credit before topping up, but the when-to-use 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 cover the safety profile (destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real context the annotations don't: the audio argument can be a remote URL, a data URI, or a local path over stdio, and it lists accepted formats. It says nothing about cost, latency, or job/response behavior, and readOnlyHint=false is never explained.

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 short sentences, zero filler, with the core purpose front-loaded before the input-form details. Every clause carries information an agent would otherwise have to guess.

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 should say what comes back, especially since `response_format` (json/text/verbose_json) is an enum with no explanation anywhere. Input side is well covered; the return-value side is a real hole for a 6-parameter 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 coverage is 67%, and the description compensates for the undocumented required `audio` parameter by spelling out its accepted forms (URL, data URI, local path) and container formats — much more than the bare `type: string` in the schema. It adds nothing for model, route, prompt, language, or response_format, which the schema already documents.

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: "Speech to text (Whisper-compatible)", immediately distinguishable from the sibling carpe_tts which goes the other direction. It does not explicitly name that sibling, but the direction of the operation is unambiguous.

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

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

There is no when-to-use or when-not guidance, no mention of when to pick this over carpe_tts / carpe_chat, and no note about cost or credit implications. Usage is only implied by the one-line purpose statement.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), the description adds genuinely useful behavior: per-character billing, the hard input-length ceiling, and the constraint that a cloned voice is bound to a specific route and model. It omits the return shape (inline audio bytes vs. a URL) and any failure modes, which matters since 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?

Four short sentences with the core action and limit front-loaded, followed by voice handling and the billing note. Nothing is padding, and the sibling references are placed where an agent consuming the text will hit them before deciding how to call.

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

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

For a six-parameter synthesis call with no output schema and no nested objects, the description covers action, limit, voice resolution, route binding, and billing — enough to invoke it correctly. The remaining gaps are the return form of the audio and the semantics of speed and response_format.

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 50%: model, route, and voice are documented in-schema, while speed, response_format, and the input string carry no description. The description compensates well for voice (model-specificity, vv_ prefixes, route binding) and repeats the input length, but says nothing about speed units or what the six response_format values imply, so the gap is only partly 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 first sentence gives a specific verb and resource ('Turn text ... into speech') plus the input constraint (≤ 4096 characters), which unambiguously separates it from the inverse sibling carpe_transcribe and from the non-synthesis sibling carpe_voice_clone.

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 conditional guidance: omit voice to take the model default, use carpe_model_details to read a model's voices, and note that cloned voices only work on route "carpe" with the model they were cloned for. It does not explain when to choose route "router" versus "carpe", which is a meaningful decision left to the schema and the CARPE_DEFAULT_ROUTE default.

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 genuinely useful context beyond them: deterministic newest-first ordering and the fact that the call is free, which saves an agent from cost anxiety. It does not state pagination/total-count behavior, but given the annotation coverage this is solidly above baseline.

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 compact sentence with the resource and ordering front-loaded, followed by a field inventory and a one-word cost note. No filler or repetition, and each clause carries information an agent would otherwise have to discover by calling the tool.

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

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

With no output schema, the description does the necessary work of enumerating returned fields and their ordering, which is exactly what an agent needs to decide whether this tool answers its question. Minor gaps remain around result caps and how filters combine, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 75% and the description never references any of the four parameters by name; 'days', 'limit', 'offset', and 'market' filtering are documented only in the schema. 'Newest first' is the only hint relevant to pagination, and 'market that served' only loosely relates to the market filter, so almost nothing is added beyond the schema.

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

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

States a specific resource with scope: per-request (not aggregate) history of the account, ordered newest first, and enumerates the fields returned (model, provider pseudonym, tokens, cost, market, routing reason, latency, savings). That contrasts implicitly with aggregate siblings like carpe_usage_summary, though no sibling is named explicitly, which keeps it from a 5.

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

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

There is no explicit when-to-use guidance, no exclusion of alternatives, and no prerequisites. With 31 sibling tools including carpe_usage_summary, carpe_key_usage, and carpe_routing_summary, an agent is left to infer from the phrase 'per-request history' that this is the detail-level view rather than the aggregate one.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds two genuine behavioral facts not in the annotations: that the call is free and that the window defaults to 7 days. It does not describe the shape of the aggregation (totals per model per day) beyond the one-line summary, but nothing here contradicts the annotations.

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

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

A single sentence front-loads what is aggregated, then the window semantics, then the cost note. No filler; the trailing 'Free.' fragment is terse but carries real decision value for a paid-API toolset.

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-optional-parameter read-only tool with no output schema, the description covers scope, aggregation granularity, window bounds, default and cost. The only remaining ambiguity is whether results are account-wide or scoped to the calling key, which matters given the carpe_key_usage and carpe_session_spend siblings.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does: 'days' means the last N days, is bounded 1–90, and defaults to 7. The default is the notable addition, since the schema's minimum/maximum alone do not communicate it.

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

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

The description names a specific resource (account spend) and the two aggregation dimensions (by model, by day) plus the time window. 'Account spend' implicitly separates it from siblings like carpe_key_usage and carpe_session_spend, but no sibling is named explicitly, so the differentiation is inferred 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?

Usage is only implied: an agent can infer this is the account-level aggregate view as opposed to per-key or per-session breakdowns. There is no explicit when-to-use statement, no guidance on when to prefer carpe_usage_history or carpe_key_usage, and no prerequisites mentioned.

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

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

Beyond the annotations (openWorld=true, idempotent=false, destructive=false), it discloses real behavior: the payload is priced first with a free quote, calls are refused locally above CARPE_MAX_PER_CALL_USD, and the call returns a job_id for asynchronous completion taking minutes. It omits the consent-refusal flow (NEEDS_CONSENT) and any rate-limit detail, but the cost/budget and async semantics are the operationally important parts.

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 dense sentences, front-loaded with the action and capability set, followed by cost behavior and the async follow-up path. The model-name list (Sora, Veo, Kling, Seedance, Wan, LTX, Grok Imagine) is slightly padded but signals coverage breadth usefully.

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 16-parameter, nested-object, asynchronous mutation with no output schema, the description covers the essentials an agent needs: what gets created, that it costs money and can be refused, what is returned (job_id), and how to finish the job. Remaining gaps are per-field semantics, which the schema partially covers.

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 56%, so several parameters (resolution, aspect_ratio, end_image_url, negative_prompt, reference_* arrays, extra, route) are undocumented in both places. The description partially compensates by pointing to carpe_model_details for valid durations/aspect ratios/resolutions and by framing the payload as priced, but it adds no syntax or meaning for the remaining undocumented fields.

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

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

States a specific verb and resource ('Queue a video') plus the modalities it covers (text-to-video, image-to-video, reference-to-video) and example models. It is clearly distinguishable from the sibling carpe_video_status (which downloads) and carpe_model_details (which lists constraints).

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: poll/download with carpe_video_status once ready, and read durations/aspect ratios/resolutions with carpe_model_details before calling. It does not state exclusions (e.g., use carpe_image_generate for stills), so the alternative-selection guidance is clear but not exhaustive.

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

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

Annotations declare readOnlyHint=false but do not say why; the description supplies the reason, namely that a completed job writes an MP4 to CARPE_OUTPUT_DIR (falling back to the temp dir) and returns the path, plus the 'Free' cost note. It does not explain what is returned while the job is still running or what happens if the same job is polled again after download, so the idempotency claim stays unelaborated.

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, both front-loaded with the action and the side effect, with zero filler. The destination and return value are packed into the same clause rather than padded out.

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 explain returns, and it does: the local file path. Combined with the destination resolution rule, the default wait behavior from the schema, and the cost note, an agent has what it needs for a two-parameter polling 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 coverage is only 50%: wait_seconds is documented in the schema with a default of 60, but job_id has no schema description at all. The description compensates by establishing that job_id comes from carpe_video_generate, which is the provenance an agent actually needs, though it adds nothing about format or 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 gives a specific verb and resource ('Check a video job', 'downloads the MP4') and ties the tool to its producer, carpe_video_generate. That linkage plus the video-specific naming cleanly separates it from the sibling status tools carpe_image_status and carpe_music_status.

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

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

It states the context of use: poll a job created by carpe_video_generate, and the schema notes 'Poll later with the status tool' for deferred checks. It never names an explicit alternative or a when-not-to-use condition, so it stops short of full routing guidance.

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

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

Adds substantial facts the annotations do not carry: the upload itself is free but requires a funded account, the returned handle expires in roughly 7 days, and cloning is consent-gated. One nuance: the sample may be an https:// URL, which implies an outbound fetch despite openWorldHint=false — a mild tension an agent should not have to resolve on its own. No error or failure-mode behavior is described.

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 front-loaded sentences with no filler; the action and payoff come first, constraints second. The parenthetical '(route "carpe", same model)' is jargon-dense and slightly slows comprehension, but nothing is expendable.

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

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

With no output schema, the description still conveys the return value (a vv_… handle) and its lifetime, plus the cost and consent preconditions — enough to call it correctly and to know what comes back. Remaining gaps are minor: failure behavior for rejected samples or unfunded accounts.

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 all three parameters are already documented, and the baseline is 3. The description adds modest meaning — the sample should be short and single-speaker, and the clone uses the same model as carpe_tts — but says nothing about the model parameter's tradeoffs beyond the schema's default.

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 concrete verb and resource (upload a reference sample, clone a voice) and states the outcome explicitly: a vv_… voice handle for carpe_tts. It routes the agent to the consuming sibling (carpe_tts, route "carpe", same model), so it is distinguishable from every other sibling 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?

Gives real preconditions: a short sample with exactly one speaker, a funded account, and consent that must be genuine. It also states the handle's downstream use via carpe_tts. It stops short of explicit negative guidance (e.g., when to reuse an existing handle instead of re-cloning, or what to do if the sample has multiple speakers).

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 openWorldHint=true and destructiveHint=false, so the description's main contribution is the cost model ('Flat fee per call'), which is decision-relevant and consistent with readOnlyHint=false and idempotentHint=false — repeat calls are billed. It does not mention auth requirements, rate limits, or failure behavior for unreachable pages, 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?

Three short front-loaded fragments with no padding, and the core (fetch one page as text/markdown) leads. The trailing 'Always on /v1' is cryptic — it is unclear whether it means endpoint version, path prefix, or an API constraint — so it costs a little clarity for little gain.

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 should say more about what comes back, but the stated text/markdown return covers the essentials and the flat-fee notice covers cost. The nested `extra` object and the absence of any search-vs-scrape routing guidance leave meaningful gaps for a paid, open-world call.

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

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

Schema description coverage is 0% across two parameters, so the description carries the full burden and it explains neither parameter. The `url` field is at least self-evident from its uri format, but `extra` — a nested free-form object with additionalProperties — is completely unexplained anywhere, leaving an agent no basis for populating it.

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

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

States a specific verb and resource ('Fetch one web page') and specifies the return format ('as text/markdown'). The word 'one' signals single-page retrieval, which implicitly contrasts with the sibling carpe_web_search, but the description never names that sibling, so the differentiation must be inferred.

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

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

Usage is only implied: an agent can infer this is for retrieving the contents of a known URL rather than discovering pages. There is no explicit when-to-use, no when-not, and no named alternative such as carpe_web_search for query-based discovery.

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 openWorldHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuinely non-structured context: routing is pinned to /v1 with no market arbitration, and the call is billed a flat fee referenced to carpe_pricing model augment-search — material for an agent managing spend. It stops short of describing what comes back or how results are shaped or ranked.

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, front-loaded with the capability, then routing, then cost. The routing sentence ('no market arbitrates web search') is jargon-heavy but does carry real meaning; nothing is padded or repeated.

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 tool with no output schema, an agent still needs the result shape and query semantics before calling, and neither is present. The billing and routing disclosure is helpful, but the required-parameter behavior and returned fields remain unspecified.

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 only 50%: the required 'query' string has no description at all (just minLength 1), and the nested 'extra' object is only loosely documented. The description contributes nothing about query format (natural language? keywords?) or which Venice augment/search options belong in 'extra', so the coverage gap is not compensated.

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 concrete verb and resource — 'Live web search through Carpe' — and identifies the backing endpoint (Venice augment/search), so an agent knows exactly what it does. It does not draw the boundary against the nearby sibling carpe_web_scrape, which is the one confusion an agent could realistically hit.

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 'live web search' plus the pointer to carpe_pricing for the flat fee, which is real decision-support for a paid call. It never states when to prefer carpe_web_scrape or carpe_chat instead, so routing between the search and scrape siblings 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?

readOnlyHint/idempotent/non-destructive are already declared, so the description's job is to add context — which it does by disclosing that the call is free and that it is scoped to x402 mode. It does not say whether the USDC balance is read live on-chain or from an internal ledger, which is the one remaining behavioral ambiguity.

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 mode restriction and then lists the returned fields, ending with the cost note. 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?

With no output schema, the description correctly compensates by enumerating what the response contains, which is the right call for a zero-parameter status tool. Only a note on freshness of the balance would make it fully complete.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-related omissions 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?

The description names a concrete resource (the agent wallet) and enumerates the specific fields it reports: address, USDC balance on Base, permit budget, billed amount, and remainder. The 'x402 mode only' qualifier implicitly separates it from the general balance/status siblings, though it never names one outright.

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?

'x402 mode only' is a real precondition that tells an agent when this tool is applicable, and 'Free' signals there is no cost to calling it. However, it does not name an alternative for non-x402 contexts (e.g. carpe_balance), leaving the agent to infer the routing itself.

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