Zero to Hundred marketplace

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

Goes beyond the readOnly/idempotent annotations by disclosing that unavailable software is silently dropped without status disclosure — a genuinely non-obvious behavior an agent must account for in reporting. Also bounds the tool with "cannot purchase software or access private source." Minor gap: no guidance on what happens if all slugs are unavailable.

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

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

Three tight sentences, zero filler. The capability statement comes first, followed by return contents, then behavioral caveats — a clean front-loaded structure.

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, full parameter descriptions, and rich annotations, the description covers what remains: scope of data returned and the silent-omission behavior. It leaves out error handling for invalid or non-public slugs, which is the only meaningful residual gap.

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

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

Schema coverage is 100% and already documents minItems 2 / maxItems 4 and the ordering semantics, so the schema does the heavy lifting. The description's word "shortlist" only loosely echoes the array constraint and adds no new syntax or format detail.

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 (compare) and resource (public marketplace software shortlist) plus what the response contains: descriptions, USD license prices, types, tech stacks. It is clearly distinguishable from z2h_search_marketplace (discovery) and z2h_get_listing (single fetch).

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?

Anchors usage to "a shortlist of public software from marketplace search," implying it is the follow-up step after search and before a decision. It does not explicitly name when to use z2h_get_listing instead, so it falls short of the full when/when-not/alternatives bar.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so safety is covered. The description adds real context beyond that: the server persists the accepted ownership wording with the source change, and the call requires an explicit legal attestation with a fixed version string. It does not discuss retry/failure behavior for a non-idempotent confirm.

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: sequencing first, then the required attestation values, then the scope boundary. No filler, no restatement of the name, and the most decision-relevant fact leads.

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 destructive, non-idempotent confirm step with an output schema present, the description supplies everything the agent needs: when it is valid, what values to send, what the server records, and what this tool deliberately does not do. Return values are left to the output schema, as appropriate.

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. The description still earns credit by explaining the intent behind the two const-valued flags (ownershipAccepted=true and ownershipVersion=2026-09-27) — that they attest to the exact statement shown — which is semantic meaning the enum/const alone doesn't convey.

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

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

Uses a specific verb+resource pair ('verify and attach the archive to the owned draft') and pins the exact lifecycle moment ('after the signed PUT succeeds'), which distinguishes it from z2h_request_source_upload and the listing-management siblings. It stops short of naming a sibling tool outright, but the sequencing makes the boundary 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?

Gives a clear precondition — call only after the signed PUT completes — and an explicit exclusion: 'Final review and publishing stay in the web wizard,' so the agent won't try to over-extend this call. No alternative tool is named as a substitute, which keeps it at 4 rather than 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?

Adds substantial context beyond the annotations: the draft is invisible (not published), write scope is required, warnings are quality advice about the saved draft and never an error, and replaying the same key returns the original draft unchanged rather than creating a second listing. This meaningfully explains the retry story that the idempotentHint=false annotation would otherwise leave ambiguous. The one unexplained point is why destructiveHint=true is set on a draft-creation tool, which an agent may find disconcerting.

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 and return payload are front-loaded, and the retry/idempotency rules follow in logical order with no filler sentences. Some clauses are tightly packed (the warnings sentence carries two ideas at once), and the return-value sentence partially overlaps the output schema, but overall the length is justified for a 20-parameter mutation.

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 20-parameter, open-world, non-read-only create tool with an output schema, the description covers the essentials: preconditions, draft visibility, retry safety, warning semantics, and where the workflow hands off. It does not address the destructive annotation, rate limits, or what happens to an abandoned draft, which leaves minor gaps for an agent reasoning about side effects.

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 the schema already carries per-field meaning and the baseline is 3. The description does add decision-level guidance for two fields (askingPrice and sourceCodeIncluded are Builder decisions; omission records false), but it does not extend to the remaining eighteen 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?

Opens with a specific verb and resource: "Create an invisible draft and return editUrl and publishUrl." The word "draft" plus the return payload makes it distinguishable from z2h_update_draft_listing and z2h_confirm_source_upload, though the description never names the sibling to use for edits (that routing only appears inside the idempotencyKey schema 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?

Gives concrete conditions: requires listings:write, set sourceCodeIncluded only after confirmation, supply and reuse an idempotencyKey on retries, and if no key was supplied check z2h_list_my_listings before retrying. It also scopes the tool's boundary by stating that source delivery, review and publishing continue in the web wizard. It stops short of an explicit "when not to use this / use update_draft_listing instead" statement in the description body.

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 readOnly/idempotent/non-destructive annotations, it discloses the required scope (listings:read), enumerates the returned fields, and explains that missing and not-owned listings both return not found — a meaningful behavioral detail (no existence leak) an agent could not infer from annotations or 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?

Five short sentences, front-loaded with the action and the permission gate, then return shape, then error semantics, then the negative constraint. 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-parameter read tool with an output schema already defining return values, the description still covers auth, error behavior and the non-download caveat. Nothing needed 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 coverage is 100% and the single slug parameter is already fully documented, including copying it from z2h_list_my_listings or z2h_create_draft_listing. The description's slug guidance duplicates the schema rather than extending it, so baseline 3 applies.

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

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

States a specific verb and resource ("Read one owned listing") plus the scope qualifier "owned" and the intent "before editing it". It is clearly distinguishable from z2h_list_my_listings (plural list) and z2h_search_marketplace (public search).

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 to use a slug from z2h_list_my_listings, frames the correct timing (before editing), and adds an exclusion — it does not download source code — which routes the agent to the upload/confirm tools when that is the actual goal.

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 readOnly/idempotent annotations: states the required scope (listings:read), enumerates what is returned (slugs, publication state, USD prices, edit links, nextCursor), explains paging termination (null ends the list), and describes the expired-token recovery path. This is 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?

Four dense sentences, front-loaded with purpose and scoping, then prerequisites, returns, and paging. No filler and nothing repeated from structured fields unnecessarily.

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 paginated list tool with an output schema, this covers everything: auth scope, page size default behavior, continuation semantics, and failure handling. 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 limit and cursor are already documented in the schema; the description only reinforces cursor-based continuation. It says nothing about the setupCode connection-check parameter, which is left entirely to the schema.

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

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

States a specific verb and resource ('Find the authenticated Builder's drafts and live listings') with clear ownership scope, which separates it from z2h_get_listing and z2h_search_marketplace. The mention of checking before creating another draft fixes the intent precisely.

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 clear trigger: use it before creating another draft, implicitly routing the agent away from z2h_create_draft_listing when a duplicate may exist. It does not explicitly name exclusions or alternatives for the search/compare siblings, but the context is unambiguous.

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

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

Annotations already declare destructiveHint, non-idempotency and open-world behavior, so the bar is lower. The description nonetheless adds real operational context: the URL is short-lived, must be kept private, caps at 100 MB, and 'does not publish'—mitigating the scary destructive hint. The URL's actual lifetime and whether re-requests invalidate prior URLs are left unstated.

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 in the first clause, and the required statement text is unavoidable verbatim content. However, the sentence enumerating signedUrl/objectKey/contentType largely restates what the output schema already provides, which is wasted space given an output schema exists.

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?

Covers the full call chain an agent needs: precondition, user-confirmation gate, size cap, upload target, privacy caution, and the mandatory follow-up tool. With an output schema present, it need not describe return values—so nothing material 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 defines every parameter, making 3 the baseline. The description adds meaning beyond the schema by embedding the literal ownership statement and pinning the acceptance semantics of ownershipAccepted/ownershipVersion to that exact wording.

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 a short-lived signed archive URL') scoped to 'an owned draft.' The follow-on step is named explicitly (z2h_confirm_source_upload), so the agent can distinguish this from the confirmation tool it sits next to in the workflow.

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 clear precondition ('For an owned draft'), the exact user confirmation gate, and the required sequencing (PUT to signedUrl, then call z2h_confirm_source_upload). It does not spell out the negative case—e.g., when to re-request a URL or what to do if the URL expires—which keeps 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 already cover read-only/idempotent/open-world, and the description adds substantial non-annotation context: no sign-in required, what fields come back, lexical (not semantic) matching, a pagination gotcha ('hasMore true without nextCursor' means narrow the query), error/rate-limit retry behavior, and a suitability disclaimer. This is exactly the kind of operational detail structured fields cannot carry.

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 in the first clause, then packed with high-value operational facts in terse sentences. No filler; nearly every sentence maps to a distinct agent decision.

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

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

For an 8-parameter read-only search with an output schema, this covers intent, example invocation, result contents, pagination edge case, error handling, and sibling routing. 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 coverage is 100%, so the baseline is 3; the description adds a concrete call example ({"search": "invoice", "limit": 5}), clarifies that an omitted search browses recent items, and ties 'lexical' matching to the search param and nextCursor to the cursor param. It doesn't clarify the interaction of sort defaults with the filter arrays, so it stays just above baseline rather than excelling.

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 ('Find live software by keyword') and immediately frames the decision it supports ('before building from scratch'). It also explicitly separates itself from z2h_compare_marketplace_listings (shortlist) and z2h_show_marketplace (cards), so an agent can route without opening schemas.

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 reasoning ('before building from scratch'), names two alternative siblings with the condition that selects each, and covers the degenerate case ('Empty search browses recent software'). Exclusions and the fallback path are both 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 read-only, idempotent, open-world behavior, so the bar is lower. The description still adds useful context beyond them: prices and availability are refreshed server-side, and listing links open the external Zero to Hundred website — behavior an agent could not infer from structured fields.

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 what is rendered, then the workflow, then defaults and side notes. Every sentence carries information, though the closing sentence about listing links is slightly tangential and could be tightened.

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, and the description covers the search-then-show workflow, the empty-input default, and server-side refresh. Only the distinction from z2h_compare_marketplace_listings is left unaddressed.

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 both parameters are already fully documented in the schema, and the description largely restates that slugs select the cards and search only prefills the panel. It adds the rationale for passing the originating query, but no syntax or format detail beyond the schema.

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

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

States a specific verb and resource — renders public software cards plus an interactive comparison panel — and gives the default behavior (newest live software when no slugs). It hints at a prerequisite relationship with z2h_search_marketplace but never explicitly contrasts itself with the similar-sounding z2h_compare_marketplace_listings sibling.

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 sequence: search first with z2h_search_marketplace, then pass the resulting public slugs here. It also states the no-argument path (omit slugs to show the newest live software), so both branches of use are covered without 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?

The annotations already declare the write/destructive/idempotent profile, and the description adds genuinely independent facts: PATCH-style merge semantics, null-to-clear behavior, the listings:write permission requirement, and the key nuance that returned warnings are quality advice and never errors. That last point materially changes how an agent would interpret a response. The remaining gap is that it does not say what a conflict looks like or what happens to publication state when a draft is edited.

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?

Five short sentences, front-loaded with the operation and merge semantics, with no filler. One sentence describing the return payload (draft identity, edit/review links, warnings) partly restates what the output schema already covers, though the "never an error" qualifier rescues 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?

For a 21-parameter mutation tool with an output schema, the description covers the things an agent must know: ownership scope, merge/clear semantics, permission requirement, excluded case, and conflict recovery. It omits what an agent should do instead when the target is a live listing, and does not mention how slug relates to the mutable fields beyond the schema.

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 per-parameter meaning is already fully documented and the baseline of 3 applies. The description does add cross-cutting semantics that apply to all 20 optional fields (omitted = unchanged, null = cleared), which the schema documents only field by field, but it offers no field-level guidance beyond that.

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 opening sentence gives a specific verb and resource ("Update an owned draft") and immediately bounds the scope to drafts the caller owns. The explicit exclusion of live listings separates it from any editing path on published listings, and the name-plus-description pair makes it distinguishable from z2h_create_draft_listing 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?

It states a clear negative condition (live listings cannot be edited here) and a recovery procedure ("On conflict, read the listing again before retrying"), which is real when-to-use guidance. It stops short of naming the sibling an agent should use for live listings or for creation, so the routing is only half-explicit.

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