parcelapi.net

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

No annotations exist, so the description carries the full burden and does so well: it discloses that the tool itself charges nothing, that a human must complete payment out-of-band, how credits are routed (to the API key, or to a newly created key), and that key claiming happens only once. These are non-obvious side effects an agent could not infer from the 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 tight sentences, each front-loaded with the decision-relevant fact (link creation, who pays, key routing, follow-up call). Nothing is filler and the workflow order matches how an agent would execute it.

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 covers the essential return artifacts (the link and the session_id) and the post-payment claim step. It stops short of describing failure modes such as an invalid pack or an already-claimed session, which would help a fully autonomous agent.

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 'pack' parameter, so the description must compensate. It does so partially by directing the agent to list_credit_packs for valid pack values, which is the key semantic an agent needs, though the exact pack identifier format is not stated.

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+resource ('Create a Stripe Checkout link to buy a credit pack') and immediately differentiates from siblings by pointing at list_credit_packs for pack selection and claim_api_key for the follow-up. An agent can distinguish this from get_credit_balance and list_credit_packs 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 tells the agent the workflow: consult list_credit_packs to choose a pack, a human must open the link to pay, and if no API key exists the agent must call claim_api_key with the returned session_id (once). It names both alternative tools and the exact conditions that select them.

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

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

With no annotations, the description carries the full burden and does well: it warns the key is shown only once, tells the agent to store it securely, and specifies the downstream Authorization: Bearer usage. Remaining gaps are re-claim behavior, expiry, and error semantics on an already-used session.

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

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

Two tight sentences with the precondition front-loaded and no filler. Every clause earns its place by adding an operational fact (source, format, one-time visibility, auth header).

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, no-output-schema tool, this covers the essential path: prerequisite, credential format, and what to do with the result. Missing only failure modes for expired or already-claimed sessions.

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 must compensate, and it does: it identifies session_id as the checkout session identifier from buy_credits and even gives the 'cs_' prefix for format validation. It does not state whether the session id is reusable or single-use.

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 (claim) plus resource (the new API key), with the originating condition spelled out. It is clearly distinguishable from sibling buy_credits, which is the step that precedes it, rather than a competing 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?

Explicitly states the trigger condition: after a buy_credits checkout that produced no key. That is a clear when-to-use with the alternative (buy_credits) named. It does not state when NOT to call it (e.g. if a key already exists or the session was already claimed).

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

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

No annotations are provided, so the description carries the full burden. It does disclose two useful traits beyond the schema: the result is scoped to 'your API key' (auth context) and the call is 'Free' (no credit consumed). It does not describe return shape or whether the read is eventually consistent, but for a zero-arg read this is close to adequate.

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 operation described first and the cost note second. Every clause earns its place.

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

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

For a parameterless read with no output schema, the description tells the agent what it gets (a credit balance), whose balance (the API key's), and the cost. Little more is needed; only the return format is left unstated, which is low stakes 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?

The tool takes no parameters, so the schema has nothing to document and there is no semantic gap to fill. Baseline for a 0-param tool is 4.

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 ('Show the remaining credit balance') scoped to the caller's API key. It points away from sibling buy_credits and list_credit_packs by nature of being a read, but never explicitly distinguishes itself from them.

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

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

Usage is implied by the resource itself: you call it when you need to know your balance. The 'Free' tag hints that cost is not a barrier, but there is no explicit when-to-use or when-not-to-use guidance relative to alternatives.

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

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

With no annotations, the description carries the full burden and does disclose real behavioral facts: the job lifecycle states (queued/running/done/failed) and that the call is cost-free. It does not cover polling cadence, job expiry, or error/not-found behavior, so it is useful but not comprehensive.

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 fragments, front-loaded with the verb and the key next-step. The 'Free.' fragment earns its place as cost information. Slightly telegraphic but no wasted 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?

For a one-parameter polling tool with no output schema and no annotations, the description supplies the essential loop (check status, then repeat the query) and the status values. It omits what a completed job returns and how failures surface, which is acceptable given the simplicity but not exhaustive.

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% and the single job_id parameter is undocumented in the schema; the description implies its origin ('started by query_parcels') but gives no format or where it is returned. It partially compensates but leaves the agent to infer the id source.

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 ('Check') and resource ('an on-demand fetch job'), and anchors it to the sibling that creates it ('started by query_parcels'). An agent can distinguish this from query_parcels and the other credit/auth siblings 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?

Explicitly says when to call it (to check a job started by query_parcels) and what to do after it completes ('repeat the same query_parcels search'), which closes the polling loop. It lacks an explicit 'when not to use' or failure-path guidance, so it falls just 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?

With no annotations, the description carries the full burden; it does disclose the auth/cost profile ('Free; no key needed') and the shape of the returned fields, which is more than most. It stops short of stating that the operation is read-only/non-mutating in explicit terms or describing pagination or result ordering.

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 waste, with the resource-scoping clause front-loaded and the cost/auth qualifier trailing. Nothing needs to be moved or 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?

For a zero-parameter catalog listing with no output schema and no annotations, the description covers purpose, cost, auth, and return fields, which is sufficient to call it correctly. Minor gaps (result ordering, whether the list is exhaustive or paginated) remain, but they are low-stakes for this 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, so the schema has nothing to document and the baseline is 4. The description's mention of returned fields (name, credits, price) is a light bonus rather than a substitute for parameter docs.

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 (List) and resource (credit packs) plus the fields returned (name, credits, price), which distinguishes it from the mutating sibling buy_credits and the account-oriented get_credit_balance. It does not explicitly name an alternative, but the phrase 'packs you can buy' makes the read-only catalog purpose 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?

'Free; no key needed' gives real context about when this call is cheap and unauthenticated to use, and the catalog framing implies it precedes buy_credits. However, no alternative is named and no explicit when-to-use/when-not guidance is given, leaving routing 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 no annotations, the description carries the full burden and does so richly: it discloses the returned fields, an explicit negative constraint ('never owner data'), a cost model (1 credit/record, minimum 1, timeouts free), and the asynchronous fetch_queued/job_id behavior. This is exactly the behavioral context an agent needs before calling.

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 purpose, then requirements, returns, cost, edge case, and pagination in that order. Despite packing in a lot, each sentence conveys a distinct, non-redundant fact 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?

No output schema or annotations exist to offload anything, yet the description covers return fields, cost, async status handling, and pagination limits. An agent has everything required to invoke this correctly and interpret its edge-case 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 description coverage is 0%, so the description must compensate, and it does for every parameter: state as a 2-letter code, county with format examples and variants, city as prefix, address as prefix with example, limit 1-100, and offset for paging. No parameter is left ambiguous.

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 ('Search US property parcels') that is instantly distinguishable from the sibling query_permits, and immediately follows with input requirements. An agent knows exactly what domain this tool covers 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 explicit operational workflow: required state, optional filters, and the fetch_queued -> poll get_fetch_job -> re-search loop when an area isn't loaded, naming the exact sibling to call. It does not, however, address when to prefer this over query_permits, so it stops short of full alternative routing.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that applicant/contractor personal data is stripped, that each result carries license and attribution, and that cost is 1 credit per record with a 1-credit minimum per search. It omits pagination behavior (limit/offset) and any auth or rate-limit context, which keeps 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?

Roughly four compact sentences, front-loaded with the core purpose and required parameter, with no filler. The clauses are dense and slightly list-like, but every sentence (including the privacy and cost statements) carries information the agent needs.

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 9-parameter read tool with no annotations and no output schema, the description covers the essential ground: required/optional filters, date formats, privacy handling, result contents, and cost. What remains missing is pagination semantics and confirmation that this is a non-mutating read, but neither is fatal.

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 compensate, and it does: it marks 'state' as required, notes 'address' is a prefix match, and specifies the YYYY-MM-DD format for issued_after/issued_before. Only limit and offset go undocumented, though those are self-evident pagination parameters.

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 ('Search building permits') plus the source constraint ('cleared open-data sources'), which is enough to distinguish it from a generic search tool. It never names or contrasts with the closest sibling, query_parcels, so an agent must infer the resource distinction 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?

The description implies the usage context by listing the filter set and stating that 'state' is required, so the agent can infer a filtered lookup over permit records. It gives no explicit when-to-use versus alternatives, no exclusions, and no prerequisite/authentication guidance despite the credit-based cost.

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