Zero to Hundred marketplace

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds real behavioral facts: unavailable software is silently omitted with no status disclosure, and the tool cannot purchase software or reach private source. These failure-mode and capability boundaries are not derivable from the annotations.

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

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

Four tight sentences, front-loaded with the core action and scope; nothing is padded. The middle sentence enumerating returned fields is somewhat redundant given an output schema exists, costing 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 annotations covering safety, a 100%-covered single-parameter schema, and an output schema documenting the return shape, the description supplies everything else an agent needs: input provenance, count limits, silent-omission behavior, and capability boundaries.

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 the 2-4 item bounds and ordering, so the baseline is 3; the description slightly reinforces the count constraint and adds provenance (slugs originate from marketplace search, implying z2h_search_marketplace output), which is mild but genuine added 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?

Specific verb (Refresh/compare) plus resource (2 to 4 public marketplace listing slugs) with a stated scope limit. It is clearly distinguishable from z2h_get_listing (single listing) and z2h_search_marketplace (discovery) by naming the comparison use case and pointing at slugs produced by 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?

States the prerequisite origin of inputs (slugs from marketplace search) and the comparison context, which tells the agent this runs after discovery. It does not, however, explicitly exclude alternatives or say when to use z2h_get_listing or z2h_show_marketplace instead.

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, readOnlyHint=false, idempotentHint=false, and openWorldHint=true. The description adds that the server records the accepted ownership wording, but does not explain failure modes, auth requirements, or what exactly is destroyed. Extra context is minimal beyond annotations.

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

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

The description is front-loaded with the action and prerequisite, then covers the ownership attestation and boundary notes. It is well-structured with no obvious filler, though the quoted ownership statement and version repeat schema constants slightly.

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

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

Given six required parameters, an output schema, and annotations covering safety hints, the description supplies the missing flow context (post-PUT confirmation, ownership attestation, publishing elsewhere). It is nearly complete, lacking only edge-case or error-handling detail.

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

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

Schema description coverage is 100%, so all six parameters are well documented in the schema itself. The description repeats the required ownershipAccepted and ownershipVersion values, but adds no syntax or constraint details beyond what the schema provides. Baseline 3 applies when schema does the heavy lifting.

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

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

The description states a specific verb (confirm/attach) and resource (source archive to the owned draft), and it clarifies the exact step in the upload flow. It distinguishes itself from sibling tools like z2h_request_source_upload by describing the post-PUT confirmation action.

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 clear prerequisite: 'After the signed PUT succeeds,' and explicitly excludes final review and publishing ('stay in the web wizard'). No alternative sibling is named, but the flow context is sufficient for correct usage.

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 non-idempotent, non-read-only, destructive and open-world. The description reinforces the important one ('creation is not idempotent') and adds material context the annotations lack: the listings:write permission requirement, that the draft is invisible, and that the flow hands off to the web wizard.

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?

Dense but front-loaded, leading with the action and return artifacts before caveats. Every sentence carries distinct information (permissions, defaults, retry safety, handoff), though the block is packed tightly enough that a reader must parse carefully.

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, return values need not be narrated, and the description still surfaces the auth requirement, non-idempotency, and the web-wizard continuation. The only gap is the unstated relationship to z2h_update_draft_listing for post-creation edits.

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 baseline is 3, but the description adds genuine semantics beyond the schema: askingPrice and source inclusion are Builder decisions, and omitted values default to false. That default-value and ownership guidance is not recoverable from the field descriptions alone.

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 immediately names the artifacts returned (editUrl, publishUrl). The 'draft' and 'invisible' framing cleanly separates it from sibling z2h_update_draft_listing.

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 real operational guidance: confirm sourceCodeIncluded before setting it, check z2h_list_my_listings before retrying, and finish source delivery/review/publishing in the web wizard. It stops short of explicitly contrasting when to call this vs z2h_update_draft_listing, so not a full 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 readOnly/idempotent/non-destructive, and the description layers on genuinely new behavior: the required 'listings:read' scope, the return contents (descriptions, pricing, software attributes, source attachment state, web edit links), and the error semantics that missing and not-owned listings both surface as not found rather than distinguishing them. That last point is a non-obvious behavioral fact an agent needs to avoid misdiagnosing a 404.

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?

Six short sentences, front-loaded with the core action and purpose, then requirements, parameter provenance, return shape, error behavior and one key exclusion. Every sentence carries distinct information with no repetition.

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 annotations covering the safety profile, an output schema covering the return shape, and a single fully documented parameter, the remaining gaps are auth scope and error semantics, both of which the description supplies. An agent has everything needed to select and call this correctly.

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

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

Schema description coverage is 100% and the schema already documents the slug's source and length bounds, so the schema carries the parameter burden. The description's slug line largely repeats what is in the schema and adds no new format or constraint detail, making the baseline 3 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?

States a specific verb and resource ('Read one owned listing') and scopes it to owned listings, which separates it from the marketplace-reading siblings like z2h_show_marketplace and z2h_search_marketplace. It also explicitly negates a plausible wrong reading ('This does not download source code'), so the agent can tell it apart from the source-upload tools 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?

Gives clear context ('before editing it') and tells the agent where the required slug comes from ('Use a slug from z2h_list_my_listings'), which is a usage prerequisite rather than just a parameter restatement. It stops short of explicitly naming the sibling to use instead when the goal is marketplace browsing or source download, so it is clear but not fully routed.

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, and non-destructive behavior. The description adds meaningful context beyond them: the listings:read requirement, pagination continuation via nextCursor, null termination, and the sign-in requirement for invalid or expired tokens.

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 information is front-loaded: purpose, auth requirement, return shape, and pagination behavior follow in quick succession. Every clause contributes useful information without padding.

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

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

For a read-only, simple listing tool with full schema coverage and an output schema, the description is complete enough. It covers purpose, auth, pagination, and token failure handling, leaving no critical gap for calling the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents limit and cursor. The description nevertheless adds meaning beyond the schema by explaining how to continue paging with nextCursor and that null ends the list, which is not stated in the parameter 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?

The description clearly states the verb and resource: finding the authenticated Builder's drafts and live listings. The scope ('my listings') implicitly distinguishes it from marketplace-search and single-listing siblings, but it does not explicitly name alternatives to sharpen the distinction.

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 clear usage context ('before creating another draft') and a prerequisite ('Requires listings:read'). It does not explicitly state when not to use it or name alternative tools, but the context is sufficient for an agent to place it correctly.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: the URL is short-lived, the upload limit is 100 MB, explicit ownership acceptance is mandatory, and the operation does not publish. It does not, however, elaborate on what makes the operation destructive.

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 core action, followed by clear, sequential instructions. Every sentence earns its place without redundancy, making it easy for an agent to parse and 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?

Given the complexity (5 required params, output schema present), the description covers all essential elements: the purpose, the critical acceptance requirement, the upload size limit, and the next step. It omits return value details, which is appropriate since an output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning by embedding the exact ownership statement that must be accepted and reinforcing that ownershipAccepted and ownershipVersion should only be set after acceptance. This is a meaningful addition beyond the schema's const and descriptions.

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' for an owned draft. It distinguishes itself from siblings by naming the next step (z2h_confirm_source_upload) and clarifies that it does not publish, so an agent can tell it apart from the confirmation 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?

Clearly indicates when to use it: 'For an owned draft' and outlines the required flow (obtain acceptance, pass ownership flags, PUT, then call z2h_confirm_source_upload). However, it does not explicitly state when not to use it or name alternative tools for obtaining upload URLs, leaving that to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial context beyond them: no sign-in required, lexical (not semantic) matching, the returned field set, the hasMore/nextCursor pagination quirk, error signaling via isError with rate-limit retry advice, and that a hit does not guarantee suitability or purchase availability.

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, then constraints, then routing are front-loaded, and nearly every sentence carries distinct operational information. It is denser than the ideal two-sentence shape, with several short edge-case sentences that could be tightened, but there is 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 an 8-parameter, zero-required search tool with an output schema already present, the description supplies everything an agent still needs: interaction model (lexical search, empty search), pagination behavior, error/retry handling, sibling routing, and a suitability caveat. Return-shape detail is correctly delegated to the output 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 the baseline is 3, but the description adds real meaning: a concrete invocation example ({"search": "invoice", "limit": 5}), the fact that omitting search browses recent software, and reinforcement that matching is lexical. It does not explain the less obvious filters (mode, operatingStatus, domains) beyond the schema text, so it stops short of 5.

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') plus the outcome the caller wants ('before building from scratch'). It also names the two sibling tools and the conditions that select them, so an agent can distinguish it without opening any other 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?

Explicit routing to alternatives ('Use z2h_compare_marketplace_listings for a shortlist or z2h_show_marketplace for cards'), plus edge-case guidance: empty search browses recent software, and when hasMore is true without nextCursor the search should be narrowed. When-to-use and when-to-switch are both covered.

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

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

Annotations already establish this as a safe read operation. The description adds useful context beyond annotations: prices/availability are refreshed server-side, and listing links open an external website. It doesn't cover rate limits or pagination, but the added behavioral context is solid.

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 sentences, each earning its place: purpose, workflow, fallback, and a behavioral note about refresh and external links. The workflow instruction is front-loaded.

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 value shape need not be explained. The description covers purpose, workflow, fallback behavior, and external link behavior – complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces the slug/search relationship and the search text's non-filtering role, which is helpful but mostly redundant with 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 action (show public software cards and an interactive comparison panel) on a clear resource. It is distinguishable from siblings like z2h_search_marketplace by framing itself as the display step, but it doesn't fully differentiate from z2h_compare_marketplace_listings.

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 prescribes the workflow: first search with z2h_search_marketplace, then pass the public slugs and search text. It also defines the fallback behavior (without slugs, shows newest live software), leaving little to inference.

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

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

Annotations already declare destructive=true, idempotent=false and readOnly=false, and the description adds non-redundant behavior: merge/PATCH semantics ('Omitted fields stay unchanged'), null-clearing semantics, an authorization requirement, the returned identity/edit links, and optimistic-concurrency handling on conflict. That is substantive disclosure beyond the 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?

Five short sentences, zero filler, and the most decision-relevant facts (draft-only scope, merge semantics) are front-loaded before the operational details. Every sentence carries 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 return values need not be spelled out, and the description still summarizes them. For a 21-parameter mutation tool the description covers scope, patch semantics, auth, error recovery, and the returned handle; per-field detail is fully carried by 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 description coverage is 100% and each nullable field already documents 'Null clears it; omission keeps it,' so the description's global restatement of that rule is largely duplicative. It adds a useful invariant (omission = no change) but names no fields and adds no syntax or cross-field guidance for the 21 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?

The description states a specific verb and resource with scope: 'Update an owned draft,' plus the key constraint that 'Live listings cannot be edited through this tool.' That scoping cleanly separates it from read tools and from creation, though no sibling tool (e.g. z2h_create_draft_listing or a live-listing edit path) 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?

It gives real when/when-not guidance: drafts only, live listings excluded, and a retry protocol ('On conflict, read the listing again before retrying'), plus the required scope 'listings:write'. It stops short of naming the alternative tool an agent should reach for when the target is a live listing or when it needs to re-read.

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