TaskFuel.ai

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a genuinely useful trait not present in structured data: the call itself is "Free", which matters for cost-aware planning.

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

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

A single tight sentence that front-loads the returned resource (remaining balance) and appends the secondary fact (spend so far) plus the cost note. No filler, no redundancy with the title.

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 names both returned values (remaining balance and spend). It omits minor details such as freshness/refresh behavior or whether balance can go negative, but it is adequate for a no-argument read 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?

The tool takes zero parameters (100% schema coverage, empty object), so the baseline is 4; there is nothing parameter-related to document or clarify.

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

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

"The connected account's remaining prepaid balance in USD, and what it has spent so far" names a concrete resource and its scope, and the title supplies the missing verb ("Check"). It does not need sibling differentiation since none of call/discover/feedback/get_result/quote/rate touch balance, but it also never states that.

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

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

Usage is only implied: the trailing "Free." hints this is a zero-cost probe an agent can run before paid operations, but there is no explicit when-to-use, prerequisite, or alternative named. An agent can infer the intent but is given no 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 only declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false; the description adds the material behavior: this is the only tool that spends money, spending is drawn from the user's balance, a $10 hard refusal limit, and the anti-repricing guarantee from max_amount_usd. That is exactly the context annotations cannot convey.

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

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

Front-loads the spending identity, then sequences the quote-then-call workflow, then the limits. No sentence is redundant and the parenthetical on dry_run removes a real ambiguity rather than padding.

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

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

Given openWorldHint, no output schema, and nested request bodies, the description covers cost, safety, and invocation well. It leaves one genuine gap: it never says how the result is retrieved or that get_result is the sibling for that, and it is silent on async versus synchronous completion.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: max_amount_usd should be set to the quote's price, model changes nothing about the call, and dry_run duplicates quote. It does not add detail on method/headers beyond what the schema already says.

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 (call) and resource (discovered endpoints) and immediately scopes it as the only spending tool, which cleanly separates it from quote, discover, and balance. An agent can identify its role without opening any schema.

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

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

Gives an explicit ordering contract: quote first to read the HTTP-402 price, then repeat here with max_amount_usd set to that quote. It also states the hard ceiling ($10), that dry_run is equivalent to quote, and why max_amount_usd must always be sent (repricing protection).

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/closed-world, so the safety profile is covered. The description adds real value beyond them: searching is free ('costs nothing', relevant in a paid-API context) and 'no results is a real answer' preempts the agent retrying an empty search.

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

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

Front-loaded with the purpose, then cost, then the mode/parameter mapping; nearly every clause carries routing information. The 'No results is a real answer: nothing offers that term' sentence is slightly conversational but earns its place by setting expectations.

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 0 required parameters, no output schema, and flat params, the description covers everything needed to call it correctly, including what the url+method mode returns ('full docs (parameters, request-body schema)'). Return-format detail is light but adequate given 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by specifying parameter combinatorics the schema does not: `url` + `method` must be passed together, `domain` alone lists a service's endpoints, and zero arguments returns the allowed domains.

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

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

Opens with a specific verb+resource ('Find a paid endpoint') and immediately enumerates the four distinct lookup modes, which makes it clearly distinct from siblings like quote, call, and balance. An agent can identify the tool's role without opening the schema.

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

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

Gives concrete routing guidance for each argument combination ('pass `query`' for keyword search, `domain` for one service, `url` + `method` together for one endpoint's docs, no arguments for the domain list) and frames query as 'the fastest path from a task to an endpoint'. It does not explicitly name sibling tools or state when-not to use it, keeping it short of a 5.

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

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

Annotations cover the safety profile (not read-only, not destructive, not idempotent, closed-world), and the description reinforces the non-idempotent nature with 'once per problem' while adding data-handling constraints ('do not include secrets or response data'). It does not say who consumes the feedback or what happens after submission, so it stops short of a 5.

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

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

Three sentences, all earning their place, with the routing constraint and the `rate` alternative front-loaded. The middle enumeration of feedback categories is long but each item is a distinct actionable trigger, so it is informative rather than padding.

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

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

A single-parameter, no-output-schema tool whose annotations already declare the mutation profile. The description supplies purpose, triggers, exclusions, the sibling alternative, and data-handling rules -- everything an agent needs to invoke it correctly.

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

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

There is only one parameter and schema coverage is 100%, with the schema already carrying type, min/max length, and a description. The description reinforces intent ('briefly and concretely') and adds an exclusion (no secrets or response data), but adds little syntax beyond what the schema states -- baseline 3 is right when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Tell taskfuel ... what worked and what got in the way') and immediately disambiguates the target ('the gateway, not any provider'). It also names the sibling `rate` and the condition that separates the two, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use triggers (setup/connection trouble, empty or wrong discovery, billing confusion, wrong docs, missing capability, a repeated failure pattern), an explicit when-not with the alternative ('a single endpoint's own behavior belongs in `rate`'), and cadence guidance ('once per problem'). Nothing is left to inference.

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

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

With readOnlyHint/idempotentHint already declaring the safety profile, the description still adds real value: it is free (no additional charge), results expire after 60 minutes, and omitting the argument lists recent calls newest-first. It does not describe the response payload shape, though that is partly inferred from the title.

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

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

Tight, front-loaded prose: what it does, when to use it, the costly mistake to avoid, then the invocation pattern and retention limit. Every sentence carries operative information with no filler.

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

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

For a single-optional-parameter read tool with no output schema, the description covers the call pattern, the listing fallback, the cost model, and the 60-minute retention window. Nothing an agent needs to invoke it correctly or decide between it and `call` is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds ordering semantics ('newest first') and the purpose of the omitted-argument mode that the schema field description only gestures at. It clarifies intent rather than merely restating the property.

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

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

States a specific verb and resource ('get the response from a paid call you already made') and immediately separates itself from the sibling `call` by framing it as a post-hoc fetch. An agent can distinguish it from `call`, `quote`, `balance`, and `rate` without opening any schema.

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

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

Explicitly names the trigger condition ('use it when `call` never returned'), explains the mechanism (client timeout while the call still completes and charges), and states the exclusion with a reason ('Do NOT repeat the `call`... that is a second charge'). Alternatives and non-usage are both covered.

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

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

Goes well beyond the annotations: it is free, it actually transmits the request and halts at the endpoint's HTTP-402 challenge, so the price is authoritative rather than an estimate, and nothing is ever executed (no-price endpoints return `not_quotable` with nothing sent). The only mild oddity is that the annotations mark idempotentHint=false, which the description does not explain given the read-only framing, but this is not a contradiction.

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

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

Front-loaded with the core value proposition ('read what one request would cost, without paying') and every sentence carries operational content. Slightly redundant in restating non-execution twice ('stops at the HTTP-402 challenge' and 'It never executes anything'), which costs it the top mark.

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 tool with no output schema, the description covers the return value (the authoritative price), the free/non-charging behavior, the error branch, and the pairing with `call`. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including the `max_amount_usd` ceiling semantics and the `model` no-op. The description reinforces the quote→call handoff ('identical arguments', ceiling set to the returned price) but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a precise verb+resource ('Read what one request would cost') and immediately contrasts with the paid alternative ('without paying'), naming `call` as the follow-up. An agent can distinguish `quote` from `rate`, `balance`, and `call` without opening any schema.

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

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

Gives an explicit workflow: send the identical arguments to `call` afterwards with `max_amount_usd` set to the quote, and 'Call it directly if you mean to run it.' It also names the failure branch (endpoints with no declared price are refused with `not_quotable`), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the mutation/idempotency profile is partly structured. The description still adds real operational context beyond them: re-voting replaces the prior vote, vote and report must agree, and `report` does not affect the rating. No contradictions with 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?

Front-loaded with the core action and scoping before the exceptions, and each clause does work. It is longer than strictly necessary, with some redundancy between the vote definition in the description and the schema's `vote` description.

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 four-parameter mutation tool with no output schema, the description covers the full decision surface: rating criteria, anti-patterns to avoid, report semantics, re-vote behavior, and the correct sibling for off-topic issues. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented, making 3 the baseline. The description reinforces that `method`/`url` must match `discover` output exactly and explains the intent of `report`, but adds little syntactic detail the schema does not already carry.

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 ('rate a documented endpoint you called') and immediately anchors the identifiers to how `discover` returns them. It is clearly distinguishable from siblings like `feedback`, which it names as the tool for taskfuel-level problems.

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

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

Explicit when-to-use both directions (up for expected/useful, down for broken or not worth the price), plus a negative list of things that must NOT be down-voted (missing catalog entry, own bad arguments, worked-but-wrong-fit) and an explicit routing rule to `feedback` for platform issues. One-vote-per-endpoint and changeability are also stated.

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