Zinvyl Marketplace Agent Gateway

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

With annotations already declaring readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, the description adds real value on top: the authority gate, the two possible outputs (Stripe MPP route vs human fallback), and the assurance that payment is never claimed before ledger verification. It stops short of describing failure/retry behavior for a non-idempotent write.

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

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

Three tight sentences with the core behavior front-loaded and no filler. The jargon ('Stripe MPP machine-payment route') costs a little clarity but every sentence carries 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?

For a non-idempotent, open-world purchase mutation with no output schema and undocumented nested inputs, the description covers outcome and the payment-verification guarantee well but omits error handling, whether an intent can be cancelled, and any detail about what the five required inputs must contain.

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% across five required parameters including two nested objects, yet the description only says 'Five-field' and names no field. It does not explain offer_id, task_summary, safe_scope_confirmed, or the purchase_authority structure, so it fails to compensate for the coverage gap; only the schema's own inline hint on maximum_amount helps.

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: it creates one bounded purchase intent for a fixed-scope Zinvyl service and returns a payment route. However, it never distinguishes itself from the sibling 'create_purchase_intent' or 'prepare_purchase_route', which sound like they could do the same thing, so an agent cannot fully disambiguate from the description alone.

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 an implicit precondition — it creates an intent 'only when delegated authority covers the exact fee' — but no explicit when-to-use guidance, no when-not-to-use, and no mention of the sibling tools it must be chosen over. Usage is inferable but not 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 it is a non-read-only, non-idempotent, open-world write. The description adds meaningful context beyond that: it produces a quote plus two payment routes (no-human Stripe MPP and human Checkout fallback) and explicitly does not charge or start work. It does not warn about duplicate creation, which matters given idempotentHint=false.

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 with the precondition front-loaded, followed by what the call produces and what it explicitly does not do. No filler and no repetition of schema content.

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

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

For a mutation tool with no output schema, the description conveys the key return artifacts (governed intent, quote, MPP route plus Checkout fallback) and the safety boundary that payment is not claimed. Missing only idempotency/duplicate-handling guidance, which the idempotentHint=false annotation leaves the agent to infer.

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 seven parameters, including the confirmation flags and the offer_id enum, are already documented in the schema. The description adds no parameter-level detail such as format or constraint beyond the 'exact fixed fee' framing, so the baseline 3 applies.

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

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

Names a specific verb and resource ('Creates the governed purchase intent and quote') and states the exact trigger condition ('after selecting one offer'). It also bounds what the tool is not ('does not itself claim payment or start work'), which distinguishes it from sibling pre-purchase tools like qualify_task and prepare_purchase_route.

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 sequence: use only after one offer is selected and only when the agent has explicit delegated authority for that exact fixed fee. It does not name alternative siblings or state what to do when authority is absent, so it stops short of full 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 declare readOnlyHint=false and idempotentHint=true, and the description corroborates by disclosing that unsupported needs are recorded as privacy-minimized telemetry (a write) and that submission happens 'once' (idempotent). It also clarifies a non-obvious boundary: route, budget, or tool call is never treated as payment or contact permission. That is genuine context 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?

Three tight sentences, front-loaded with the routing cue 'Start here.' Every sentence carries content (entry positioning, return behavior, permission boundary) 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?

There is no output schema, but the description compensates by describing what the call returns (best fixed-scope offer and next purchase action) and the fallback behavior. With 11 parameters at 82% schema coverage, an agent has enough to invoke it 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 82%, so the schema already documents the required authorization and sanitization flags and the optional fields. The description's 'one authorized sanitized business need' merely paraphrases the required parameters without adding format or constraint 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 outcome: submit one sanitized business need and receive the best fixed-scope offer plus the exact next purchase action, or have it recorded as telemetry. This distinguishes it from siblings like buy_service or prepare_purchase_route, though the 'Zinvyl' framing is jargon-heavy for an unfamiliar agent.

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

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

'Start here' signals this is the entry point of the flow, which is real usage guidance. However, it never names an alternative among the many siblings (match_or_capture_demand, list_offers, qualify_task) or states when NOT to use it, so the agent must infer the 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?

Annotations already declare readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile needs no restating. The description adds genuine context by characterizing the output as hard limits on what Zinvyl may claim, but it says nothing about format, size, or stability beyond that. Useful but not rich behavioral disclosure.

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

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

Two sentences, zero filler, and the sequencing instruction is front-loaded before the return-value description. Every clause carries information an 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?

With no output schema, the description does the work of telling the agent the nature of the returned data (acceptance tests, exclusions, evidence boundaries), which is enough to know why to call it. It lacks any indication of return shape or volume, a minor gap for a single-parameter read lookup.

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

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

Schema description coverage is 100% and the single parameter is a fully enumerated offer ID with its own description listing valid values. The description adds no syntax, format, or fallback detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb-plus-resource framing: it returns 'the exact delivery acceptance tests, exclusions, and evidence boundaries' for a given offer. That is clearly more than a restatement of the name. It does not, however, distinguish itself from a similarly scoped sibling such as get_purchase_requirements, which an agent might confuse with it.

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?

'Use after list_offers or qualify_task identifies an offer' gives an explicit prerequisite and names the two upstream tools that feed it. There is no when-not guidance or statement of what this call enables downstream, so it stops short of full 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 already declare readOnlyHint, idempotentHint, and closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavioral context: it is a dry-run query that returns pricing and authority constraints and explicitly does not create an intent, which tells the agent this is a non-mutating inspection step. Missing only things like error or staleness behavior.

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: the first gives the usage trigger, the second front-loads the enumerated return payload. Every clause carries information and nothing is repeated from the structured fields.

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 compensates by listing the return contents in detail, which is exactly what an agent needs before calling. Minor residual gap: no mention of failure modes or how the returned 'funding rule' and authority requirements must be honored downstream.

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

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

Schema description coverage is 100% and the single offer_id parameter is an enum with a clear schema description pointing back to list_offers/qualify_task. The description adds no format or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource (get purchase requirements) and enumerates precisely what is returned: exact price, buy_service contract, delegated-authority requirements, payment route, capacity limits, and funding rule. It also implicitly distinguishes itself from create_purchase_intent via 'without creating an intent', so an agent can separate it from siblings 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?

'Use after selecting an offer' gives a clear sequencing trigger and the closing phrase 'without creating an intent' signals the boundary against create_purchase_intent. It does not, however, explicitly name the alternative tools (create_purchase_intent, prepare_purchase_route) or state when this should be skipped.

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 a closed-world scope, so the safety profile is covered. The description adds genuine context beyond that by disclosing the returned payload fields (price, delivery window, required inputs, exclusions, intake URL), which matters because no output schema exists. It stops short of describing ordering, pagination, or lookup cost.

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, both fully loaded: the first front-loads the usage gate before any alternative is offered, the second enumerates the return contents and the downstream tool. No filler or restatement 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?

With no parameters and no output schema, the description carries the return-value burden itself and does so by naming the payload fields. Combined with the routing guidance to find_service and get_acceptance_tests, an agent has everything needed to call this correctly and place it in a workflow.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly avoids inventing filter semantics that the empty schema contradicts.

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 with explicit scope: enumerates 'Zinvyl's full seven-offer catalog', which tells the agent exactly what set is returned. It distinguishes itself from siblings by naming find_service as the different starting point and get_acceptance_tests as the follow-on step.

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 precondition ('Use only when comparing ... full seven-offer catalog'), an explicit fallback ('otherwise start with find_service'), and explicit sequencing ('use get_acceptance_tests only after selecting an offer'). When, when-not, and alternatives are all present.

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 say readOnlyHint=false and idempotentHint=true, but the description adds crucial context: it records telemetry rather than creating transactions, and explicitly lists what commitments it does NOT create. This is genuinely useful behavior disclosure beyond what annotations 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?

Three tight clauses: trigger, primary behavior, fallback behavior plus explicit non-commitments. No filler. Front-loaded with the use case.

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 11 params with 82% schema coverage and no output schema, the description supplies the essential missing context: this is a low-commitment telemetry write, not a purchase. An agent knows exactly when to call it and what not to expect from the 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 coverage is 82%, so the schema documents most parameters well, including the strict const booleans that gate sharing. The description doesn't add syntax or format details beyond the schema, and the 'sanitized' framing is already echoed in schema descriptions. 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?

Names a specific dual-purpose operation (match existing offer else record demand) and states what it does not do (no order, quote, outreach). Clearly distinguishable from siblings like find_service and buy_service.

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?

Opens with an explicit 'Use when' condition (sanitized need, unknown whether Zinvyl sells it), which distinguishes it from find_service (known request) and buy_service (commitment). The fallback behavior is specified inline.

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 flag readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds the crucial negative boundary: it does not create, fund, verify, or start an order, and returns schema + endpoint only. This is valuable context beyond annotations, though return-format details (shape, endpoint format) are not described.

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 tightly packed sentences, both front-loaded with the precondition and the negative scope. Every clause (authority requirement, return content, exclusions) 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?

Given only 2 required params, full schema coverage, and existing annotations, the description covers usage conditions, exclusions, and return intent adequately. It could add a note on what 'prepare' output looks like in practice, but the core call behavior is sufficiently complete.

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 fully documented in the schema itself. The description adds no additional parameter-level detail (e.g., which offer IDs are valid or the exact meaning of authorization), so 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?

States a specific verb (prepare) and resource (authorized funding route), and explicitly enumerates what it is not (does not create, fund, verify, or start an order). This cleanly distinguishes it from create_purchase_intent and buy_service among the siblings.

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 precondition sequence: 'Use only after selecting an offer and confirming explicit purchasing authority.' This tells the agent exactly when in the workflow the tool applies, leaving nothing 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?

Beyond the annotations (readOnlyHint, openWorldHint=false, idempotentHint), the description adds meaningful behavioral context: the three possible result categories, the absence of diagnosis, and the guarantee that no order is created. This helps the agent anticipate side-effect-free, deterministic behavior.

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 two sentences with no filler. The use condition is front-loaded, followed by return categories and explicit non-behaviors, earning every sentence's 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 single-parameter tool with no output schema and strong annotations, the description covers the invocation trigger, the possible return shapes, and the boundaries of behavior (no diagnosis, no order). Nothing essential is missing for an agent to call it 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 provides a solid description of 'summary' as a sanitized expected-versus-actual outcome with security guidance. The tool-level description does not add parameter-specific detail, so the baseline of 3 applies.

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

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

The description states a specific action ('qualify a bounded task') and a precise target state: a buyer's sanitized problem not yet mapped to an offer. It also enumerates the possible returns (one offer ID, broader-service route, or scope-reduction decision) and distinguishes itself from order-creation or diagnosis tools, making it clearly separable from its siblings.

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 opening phrase 'Use when a buyer's sanitized problem is not yet mapped to an offer' gives an explicit precondition for invocation. It implies when-not-to-use by stating it performs no diagnosis and creates no order, though it does not name alternative tools or provide explicit exclusions.

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