Perq

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantive context: embargo status with a public_after timestamp, a 30-day event window, subscription-topic filtering, and where the token comes from. It does not describe ordering or volume, keeping it 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?

Two sentences, front-loaded with the payload scope before the prerequisite. The dense parenthetical '(embargoed, each with public_after)' earns its place, though the sentence stacks several distinct concepts and could be split for readability.

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

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

For a single-parameter read-only feed tool with annotations carrying the safety profile and no output schema, the description covers content, time window, filtering, and credential acquisition. The one real omission is any statement about how this differs from the similarly-scoped recently_changed.

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 would be 3, but the description adds meaning the schema lacks: the token is a private-feed credential obtained either from subscribe (webhook) or the email confirmation page. That provenance is actionable for an agent that does not yet hold a token.

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 (verified but not-yet-public offers) plus a two-part payload: embargoed offers with public_after and 30-day offer events filtered by subscription topics. This is concrete and distinguishable from get_offer/list_packs, though it never addresses the apparent overlap with the sibling recently_changed.

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 real prerequisite (private feed token from subscribe or the email confirmation page), which tells the agent which path this belongs to, but there is no explicit when-to-use versus when-not or an alternative for the 30-day event portion that recently_changed also seems to serve. Usage is 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, closed-world. The description adds valuable non-obvious behavior: results are 'ranked' and 'verified', and closed offers are excluded unless filters.include_closed is true. It stops short of describing pagination or how ranking is computed.

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 question the tool answers, then examples, then the result field list, then the closed-offer caveat. Every sentence earns its place, though the long comma-separated field list is slightly dense.

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 enumerating returned fields (credit_value, eligibility, how_to_claim, claim_url, source_url, source_snippet, last_verified) is genuinely necessary and well done. Combined with the exclusion rule and example needs, an agent has enough to call it correctly; only ranking/pagination details are 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% (both need and the nested filters are documented with examples and slugs), so the schema carries the parameter semantics. The description echoes only the include_closed default behavior and adds no new syntax or meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a concrete verb+resource ('Answer what free credits / free tier / startup program can I get for X') and scopes the intent to ranked, verified offers matching a free-form need. It is clearly a natural-language search tool, distinguishable in spirit from siblings like get_offer or list_packs, though it never names those siblings 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?

Three vivid example queries ('free speech to text credits', 'GPU for a bootstrapped startup', 'student LLM API credits') show how to phrase a need, which is real usage guidance. However, there is no statement of when to prefer this tool over get_offer/early_offers/recently_changed, and no when-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 cover read-only, idempotent, non-destructive semantics, so the bar is lower. The description adds genuinely useful content-level context — that the record includes the source quote, last_verified timestamp, recorded changes, and containing packs — which matters because 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?

One sentence, front-loaded with the verb and resource, with the returned-field detail packed into the tail. 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?

With no output schema, describing the returned payload is the right call and it does so. Coverage is good for a single-parameter lookup; error behavior for an unknown id and any response size caveats are not mentioned but are minor.

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 states where the id comes from ('Offer id from find_credits or a pack'). The description's example id ('deepgram-200-credit') adds a little format intuition but no new semantics. Baseline 3 is appropriate.

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

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

Specific verb+resource: fetches the full record for a single Perq offer by id. It names the resource scope (one offer), gives an example id format, and enumerates what the record contains, distinguishing it from search-style siblings like find_credits.

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 — call this when you already have an offer id and need the full record, as opposed to searching. But there is no explicit statement of when to prefer this over find_credits or get_pack, and no exclusions. The pointer to the id's origin 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 this read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. Beyond that, the description adds genuinely useful behavioral content: the response includes every offer in the pack plus the derivation of the up-to total, including which offers counted and which were excluded — a real disclosure about output content that 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?

A single front-loaded sentence with no filler: resource, selector, and payload all in one pass. The parenthetical is dense but earns its place by clarifying what 'computed' means. Minor awkwardness in 'its up-to total' phrasing costs 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?

With no output schema, the description carries the return-value burden and largely does so — pack contents, offer list, and total derivation are all described. For a one-parameter read-only tool with full annotations this is close to sufficient; edge details like pagination or offer ordering are unstated but low-risk here.

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 there is a single parameter whose schema text already explains the slug format and points at list_packs. The description adds no further parameter meaning, so the baseline of 3 for well-covered schemas 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 names a specific resource (one curated pack) and selector (by slug), and states what comes back: every offer plus the total's computation basis. That distinguishes it implicitly from list_packs (many packs) and get_offer (a single offer), though no sibling is named 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?

Usage is only implied by the singular 'one curated pack by slug' — the agent can infer this is the detail fetch for a pack already found via list_packs, which the slug parameter's own schema text reinforces. There is no explicit when-to-use, when-not, or named alternative in the description itself.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds that each pack carries a headline and an 'up-to total where one is computed', which hints at the returned shape, but it says nothing about ordering, pagination, or how complete the listing is. With annotations carrying the safety burden, a 3 is appropriate.

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 core definition and then qualifies the return content. It is dense with examples but none are wasted. Slightly more readable if split, but appropriately sized.

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 listing tool with no output schema, the description does enough: it explains what a pack is and what fields accompany each entry. Missing only ordering/pagination hints and a pointer to get_pack for details, but nothing an agent needs to invoke it is absent.

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 the baseline of 4 applies. The description correctly implies a bulk listing with no filtering knobs, matching the empty schema, and adds no misleading parameter claims.

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 state the resource clearly — curated bundles of offers — and grounds it with concrete examples (AI startup launch pack, LLM API free tier pack). Combined with the name 'list_packs', the purpose is unambiguous. It stops short of differentiating from the singular sibling get_pack, but the verb/resource pairing is solid.

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 indication of when to use this tool versus siblings like get_pack, early_offers, or find_credits. No prerequisites, no exclusions, no alternatives are named. The agent must infer from the name alone that this retrieves all packs in bulk.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the semantics of 'changed': value, eligibility, and claim-step edits, plus closed offers, and the explicit America/New_York date basis. That timezone detail materially affects interpretation of the look-back window and is not derivable from the schema. Return ordering and pagination behavior remain undisclosed.

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 that front-loads the resource and the change categories, with the window and timezone as trailing qualifiers. No filler, no repetition of 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?

For a read-only two-parameter feed with full schema coverage, annotations, and no output schema, the description covers what the tool returns conceptually (offers added/updated/closed). It stops short of describing result ordering or how the limit truncates events, which an agent consuming a change feed would benefit from knowing.

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 defaults and min/max already documented for both parameters, so the schema carries the load. The description only reinforces the 'last N days' framing and adds the timezone context; it adds no syntax or format detail beyond that, matching the baseline 3.

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 resource (offers) and the change events it surfaces (added, updated, closed) within a bounded look-back window, which is more specific than the bare name 'recently_changed'. It does not explicitly contrast itself with siblings like early_offers or get_offer, so the agent must infer the difference between a change feed and a point-in-time lookup.

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 description makes clear this is a 'what changed lately' feed, but it never says when to prefer it over early_offers, get_offer, or find_credits, nor does it state any prerequisites or exclusions. An agent can guess the intent but gets 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 say readOnly=false, idempotent=false, openWorld=true; the description goes well beyond that with the double opt-in confirmation-then-digest flow, https-only/public-host restriction on webhooks, HMAC-SHA256 signing, and the fact that a webhook signup returns the signing secret once, a private feed token, and the signed verification ping result. That is precisely the behavioral context an agent needs before committing a side effect.

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 benefit and the two modes are front-loaded, and each sentence carries distinct information (opt-in flow, webhook constraints, return payload, safety constraint). It is on the dense/long side, but there is little padding to cut.

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 describes the return payload (one-time signing secret, feed token, verification ping result), covers both signup paths, and matches the non-idempotent annotation by implying each signup yields new credentials. Nothing an agent needs in order 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 baseline is 3, but the description adds real semantics: what email triggers (confirmation link, then digest only on days with news), what webhook_url requires (https, public hosts, signed POSTs), and what a webhook signup returns. Topics are left to the schema, which is acceptable since it documents them fully.

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 ('subscribe') plus the resource and benefit: newly verified offers ~24h before they go public, plus closures and changes. This cleanly separates it from siblings like early_offers (which surfaces offers) and recently_changed, so an agent can route without opening another 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 routing between the two modes ('email (a person)' vs 'webhook_url (an agent)') and a strong use constraint ('Only subscribe an address or URL the user asked you to'). What's missing is an explicit statement of when to prefer a sibling tool (e.g. reading early_offers instead of subscribing), but the mode selection is unambiguous.

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