freemoney.computer

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the bar is lower. The description still adds real behavioral context the annotations cannot: offers may overlap across providers, totals and stacking are not guaranteed, and the result is provisional until eligibility is verified — all important for how an agent should report the output.

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

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

Four short sentences, front-loaded with what is produced, followed by caveats and then the routing note. Slightly telegraphic ('Eligibility still needs checking.') but no wasted wording and no repetition of schema or annotation facts.

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?

Output schema exists, so return values need not be described, and annotations cover the safety profile. What remains is mostly the follow-up path after building a stack (verify eligibility, then claim), which is hinted at but not spelled out; otherwise the description is complete for a three-parameter 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?

Schema description coverage is 0%, so the description carries the burden. It does indicate that 'country' and 'audiences' are filters used to match offers, which adds meaning beyond bare field names, but it says nothing about the 'providers' parameter (accepted string format, whether names or IDs, limits) and nothing about country code format or the audience vocabulary.

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 output artifact ('build a candidate bundle across providers'), and the word 'candidate' plus 'eligibility still needs checking' makes clear this is a preliminary read, not a final claim. It doesn't explicitly contrast with close siblings like credits_for_stack or search_offers, but the 'candidate bundle' framing is distinctive enough to route an agent.

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

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

Gives a concrete routing rule: if a provider is missing, use request_promotion, and explicitly states this read does not create requests. It also warns that eligibility requires a subsequent check. It stops short of naming which sibling performs that follow-up check (e.g. credits_for_stack / claim_offer), so one handoff 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?

Annotations declare idempotentHint=true and destructiveHint=false, and the description reinforces idempotency concretely by telling the agent to reuse request_key across retries. It adds context the annotations cannot carry: results are best-effort ('when available'), credits are not guaranteed, and the output includes a private receipt intended for later outcome reporting. It does not describe what a failed or empty claim looks like, leaving some behavioral uncertainty.

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, each earning its place: what you get, what it does not do, the retry rule, and the follow-up step. The most dangerous misconception (that this redeems) is addressed in the second sentence, before operational details.

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?

An output schema exists, so return values need not be spelled out, yet the description still previews the code, steps, and receipt, which helps the agent plan the next turn. Idempotency, the no-redemption boundary, and the outcome-reporting loop are all covered. The remaining gap is edge-case behavior when no public code exists or when the claim is rejected.

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 both required parameters are undocumented structurally. The description rescues request_key by defining it as a retry-stable key that must be reused, which is real added meaning. offer_id receives no explanation at all, and with zero coverage the description does not fully compensate for the schema gap.

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

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

The description states a concrete return set: a reviewed public code when available, official redemption steps, and a private feedback receipt. It also explicitly disclaims what the name 'claim_offer' might imply (no redemption, no account creation, no application submission), which prevents a costly misread. It stops short of naming the sibling that actually performs the redemption, so 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 well-scoped: negative guidance lists four things this tool does not do, and the follow-up instruction ties the returned receipt to a later outcome report, implicitly routing to report_promotion_result. The retry rule (reuse request_key) is a clear operational instruction. No sibling is named explicitly, and there is no statement of prerequisites or what to do when no code is available.

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 description's job is to add context, which it does: it says the results are provider-level free credits/programs, one set per service, and instructs broad input harvesting for coverage. It adds no note on how partial matches or unknown services behave, which keeps it below a 5.

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

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

Two sentences, purpose front-loaded before the input-sourcing instruction, with no filler. The awkward mid-sentence line break and the 'For a codebase:' preamble are minor inefficiencies rather than 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?

An output schema exists and annotations cover the safety profile, so the description only needs to justify input design — which it does with the file list and the 'every external service' directive. The only residual gap is guidance on when this is the right entry point versus build_credit_stack or search_credits.

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% — services, eligible_as and per_service are each documented in the schema, including example package names. The description only reinforces the services parameter's sourcing ('pass every external service you find') and adds nothing about eligible_as or per_service, 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?

The description states a specific verb and resource — list free credits and programs offered by each service provider for a given codebase stack. That is clearly distinct from a generic search tool, though it never names search_credits or search_offers as the sibling an agent should consider instead.

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 preconditions for good input ('Read package.json, requirements.txt, pyproject.toml, go.mod, Dockerfiles, Terraform and .env.example first and pass every external service you find'), which is real when-to-use guidance tied to a workflow. It stops short of stating when not to use it or which sibling to pick for a non-codebase lookup.

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 elsewhere. The description adds the one thing annotations cannot: the output is shaped for ChatGPT consumption. It does not explain what actually differs in that shape, but with an output schema present that gap is tolerable.

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 front-loaded sentence with zero filler. It is arguably too terse, but nothing is redundant or 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?

With rich annotations, an output schema, and one fully documented parameter, the structural burden on the description is low. The remaining gap is the sibling relationship: an agent cannot tell from this text why it would call fetch rather than get_credit_program.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented as 'An id from search.' The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

The description states the tool returns get_credit_program content in a ChatGPT-specific format, which is a concrete verb+resource+shape. However, it leans on the reader already knowing what the sibling get_credit_program does, and the bare name 'fetch' gives no independent signal. The purpose is inferable but not self-standing.

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 hints at a ChatGPT deep-research / company-knowledge context but never says when to pick this over get_credit_program, or whether the two return different data. No exclusions, no prerequisites, no 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 declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds that the returned program is complete ('in full', 'every requirement') and lists the content areas, which is modest value. It says nothing about behavior for a missing or invalid 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?

A single short sentence, front-loaded with 'One program in full', then a compact enumeration. Nothing is wasted, though the fragment style makes it slightly less crisp than an explicit verb-led sentence would be.

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

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

For a one-parameter read with an output schema and full annotation coverage, little more is needed; the description conveys that the record is exhaustive rather than summary-level. Missing only edge-case behavior such as not-found handling.

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

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

Schema description coverage is 100%, and the schema itself explains that the id comes from search_credits or credits_for_stack. The description adds no meaning about the id beyond what the schema already provides, 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?

The description identifies a single-resource fetch and enumerates what the record contains (offer, eligibility, requirements, duration, links), which distinguishes it from list-style siblings like search_credits and credits_for_stack. It reads as a noun phrase rather than a verb+resource statement, so it stops short of an explicit 'retrieve one credit program by id'.

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: nothing says to call this after search_credits, nor that it should be used instead of get_offer for offer-only details. The only routing hint ('A program id from search_credits or credits_for_stack') lives in the schema, not the description.

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 the content scope and the conditional 'public code if known', which usefully flags that some data may be absent. It does not address behavior for an invalid or unknown offer_id, which is the main remaining disclosure gap.

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 dense sentence, front-loaded with the verb and resource, with no filler. Every listed item (source, eligibility gates, code, reports) conveys distinct information.

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

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

An output schema exists, so the description is not obligated to describe return values, and annotations cover the safety profile. However, for a lookup tool the only parameter is undocumented and there is no statement about what happens when the ID is not found, leaving a real 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 description coverage is 0% for the single required parameter offer_id, so the schema contributes no meaning at all. The description never explains what an offer_id is, its format, or where to get one, leaving the only input undocumented in both places.

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 ('Read') and resource ('a specific offer') and enumerates what is exposed: source, eligibility gates, public code, and community reports. That distinguishes it implicitly from sibling search tools like search_offers, though it never names the alternative lookup path explicitly.

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 specific offer' signals an ID-based lookup rather than a search, so an agent can infer this follows a search. There is no explicit when-to-use/when-not-to-use guidance, no mention of how to obtain an offer_id, and no reference to sibling tools like search_offers or claim_offer.

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 readOnly, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real value by disclosing the ownership constraint (only your own request) and the identity/auth requirement. It does not say what happens when the request is unknown or still pending, which would be the remaining useful disclosure.

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 scope, and no filler. Every clause carries information the agent can act on.

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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The gap is operational: nothing tells the agent when in the request lifecycle to call this tool or how to interpret an empty candidate-match result, which matters for a status-checking primitive.

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

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

Schema coverage is 0% for the single request_id parameter, so the description must compensate; it adds that the id refers to a request scoped to the same caller identity, which is meaningful. It still gives no format or length hints and does not clarify whether it accepts ids from other callers' submissions.

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

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

States a concrete verb and resource: reads a queued request plus its candidate matches, scoped to the caller. An agent can tell it is a read-side lookup tool, though the description never names the sibling that creates such requests (request_promotion) or otherwise differentiates itself from siblings in 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?

There is no explicit when-to-use guidance, no mention of polling after request_promotion, and no alternatives or exclusions. 'Requires the same caller identity' is a precondition, not usage guidance, so an agent must infer the workflow from context 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 a non-read-only, idempotent, non-destructive write; the description adds real context on top: only the latest report per caller/offer revision counts (so re-reporting supersedes rather than appends), and community reports are not vendor-verified validity. The latter is an important caveat about how the submitted data will be interpreted downstream.

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 no filler, leading with the action. The middle sentence ('One latest report per caller and offer revision counts') is slightly compressed to the point of awkwardness, but it is dense with meaning rather than padded.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. Still missing for a mutation tool: the prerequisite that a claim exists, where receipt_id is sourced, and what happens on an invalid or stale receipt — leaving the calling sequence partly guesswork.

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

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

Schema coverage is 0%, so the description carries the burden. It clarifies that receipt_id refers to a claim receipt, which helps, but does not say where that ID comes from (presumably a prior claim_offer response) or what distinguishes the four outcome values in ambiguous cases. The enum members are largely self-describing, keeping this at an adequate rather than deficient level.

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: reporting a redemption outcome against a claim receipt. That resource ('claim receipt') is distinct enough from siblings like claim_offer and submit_promotion_code that an agent can tell this is the feedback/reporting step rather than the request step, though no sibling is named explicitly.

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 statement of when to call this versus claim_offer, submit_promotion_code, or get_request_status — e.g. 'call after redeeming a claimed offer.' The line about one latest report per caller and offer revision is a deduplication rule, not usage guidance, so timing and prerequisites must be inferred.

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, it discloses remote auth requirements, idempotent retry behavior via request_key, privacy constraints, and the important caveat that a catalog match does not imply availability or a successful claim. These are meaningful behavioral details, though post-submission behavior is left to the 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?

The description is front-loaded with the purpose and then adds compact operational guidance. Each sentence carries useful information, though the structure is somewhat fragmented rather than tightly organized.

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 queuing/mutation tool with annotations and an output schema, it covers the most important operational concerns: authentication, retry key reuse, privacy, and claim caveats. It still omits provider format and requirements usage, which matters given the 0% schema coverage.

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

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

With 0% schema description coverage, the description must carry parameter meaning. It explains request_key as a retry/idempotency key and hints that requirements should not contain secrets, but provider is left as a bare field and requirements semantics/format are not explained.

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

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

The description states a specific verb and resource: "Queue a private request for a provider or missing promotion." It is clear what the tool does, though it does not explicitly name sibling alternatives such as claim_offer or submit_promotion_code.

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 provides useful conditions: remote authentication is required, request_key should be reused for retries, and sensitive data must not be included. However, it does not explicitly say when to use this tool instead of siblings like claim_offer, submit_promotion_code, or get_request_status, leaving routing partly implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered without description help. The description adds the two-step read pattern ('Pass an id to fetch') and the returned fields, which is real added context, but says nothing about result limits, ranking, or the maxLength-300 query constraint's consequences.

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 with the format claim front-loaded, so there is little waste. But the wording is compressed to the point of obscurity ('in the shape ChatGPT's deep research and company knowledge use') and the dangling 'Pass an id to fetch' sentence confuses rather than clarifies.

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 an output schema present and one fully documented parameter, the description only needs to convey scope, output flavor, and the follow-up path, which it does. The remaining gap is that the search domain (free credit programs) is only inferable from the title, not the description body.

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

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

Schema coverage is 100% with a single documented 'query' parameter ('What the person wants, in plain words or provider names'), so the baseline is 3. The description's 'Pass an id to fetch' does not map to any parameter in this schema and could be misread as an input, so it adds ambiguity rather than meaning.

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 operation as an equivalent of search_credits and states its output shape (ids, titles, links) in a ChatGPT deep-research form, which distinguishes it from siblings like search_offers. It never plainly says *what* is being searched (free credit programs), leaning on the title to supply that, and the tool name 'search' is generic on its own.

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 routes the agent explicitly: use search_credits instead when you need eligibility or no-card filters, implicitly reserving this tool for ChatGPT-format/deep-research consumption. The phrase 'Other apps' is loose and never states a firm when-not condition for this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that each result includes eligibility, requirements, and links, which is slight extra context. It says nothing about result volume, ranking, or empty-result behavior beyond what the annotations already imply.

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, front-loaded with the scope definition, with no filler language. The second sentence about result contents leans on information the output schema likely already provides, keeping it just short of 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?

Scope and coverage are clear and an output schema exists, so return values need no explanation. For a 7-parameter discovery tool sitting among similar search and offer siblings, the absent routing guidance is the main completeness 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 description coverage is 86%, with per-parameter descriptions for query, category, eligible_as, and the exclusion flags, so the schema does most of the work and baseline 3 applies. The description itself adds no parameter-level meaning beyond the eligibility hint ('who can get each one, what it needs').

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 (find) and a well-scoped resource (free credits, free tiers, trials, eligibility programs), plus the provider domains covered. It lets an agent distinguish this from retrieval-style siblings like get_credit_program or get_offer, though it never explicitly contrasts with search_offers.

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

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

The description gives no when-to-use guidance, no exclusions, and does not name an alternative such as search_offers, credits_for_stack, or build_credit_stack. An agent must infer from the name alone whether to call this or a sibling for a given query.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine value beyond that by disclosing what results carry (source, freshness, restrictions, community counts) and warning that an empty result set is not proof of absence — a non-obvious behavioral trait for this domain.

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

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

Purpose is front-loaded in the first sentence, followed by input guidance, parameter clarifications, result shape, and a caveat in that order. It is dense but every sentence adds a distinct piece of information; minor redundancy in the split between input and parameter sentences.

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 an output schema present, the description need not enumerate return values, yet it still summarizes result fields usefully. Five optional parameters, zero required, and strong annotation coverage mean the remaining omission (pagination semantics) is not critical for 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 description coverage is 0%, so the description must carry parameter meaning. It does explain country as an ISO two-letter code, clarifies that audiences supplement rather than replace 'anyone' offers, and describes query usage — three of five parameters. Limit and offset are undocumented but follow conventional pagination naming, leaving a modest 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 states a specific verb and resource: 'Find AI/cloud credit programs and reviewed public promo codes', which tells an agent exactly what corpus is searched. The 'reviewed public' qualifier hints at curation versus sibling tools like search_credits or get_offer, but no sibling is named explicitly, so differentiation is implicit rather than stated.

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

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

It gives input guidance ('Use a provider name or keywords') and a useful caveat that empty results do not prove no promotion exists, which shapes follow-up behavior. However, it never states when to pick this over search_credits, search, or get_offer, and provides no exclusions or prerequisites.

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=true, destructiveHint=false, openWorldHint=false. The description adds real behavior beyond that: submissions stay private, operator review is required, votes cannot promote a code to public/verified, and the server does not fetch user URLs. It never explains the idempotency contract implied by request_key, which is the most operationally important trait for a retryable write.

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

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

Front-loaded with the action, followed by prohibitions and privacy guarantees. Sentences are tight, though the votes sentence is somewhat tangential and the trailing whitespace/multi-line formatting is untidy.

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?

An output schema exists, so return values need not be described. For a 4-required-param write with zero schema coverage, the missing request_key and provider semantics leave a real gap an agent could get wrong.

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 burden. It clarifies source_url ('URLs are evidence; the server does not fetch user URLs') and implies code must be public rather than secret, but 'provider' and especially 'request_key' (8-128 chars, presumably an idempotency key) get no explanation at all.

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: submit a publicly shareable promo code plus its source for operator review. The scope ('publicly shareable', 'for operator review') separates it from claim_offer and request_promotion without naming a sibling 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?

Gives explicit when-not guidance: never submit API keys, account-specific vouchers, or secrets. It also pre-empts a misuse case (submitting to gain votes/verification). It does not name an alternative tool for the excluded cases (e.g. request_promotion), so it stops short of full routing.

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