Orbylon

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

Beyond the readOnly/idempotent annotations, it discloses how the answer is produced (only from what the business published on Orbylon), that it never guesses, and the failure shape: answered: false plus the business's phone number. This is exactly the behavioral context annotations cannot convey.

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

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

Purpose and scope are front-loaded and the alternatives arrive last, which is the right ordering. It is slightly dense—the parenthetical inventory of published data and the repeated mentions of sibling tools add length—but no sentence is filler.

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

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

With only two simple parameters, full schema coverage, and no output schema, the description still explains the response semantics (answered: false and the fallback phone number) and the tool's limits. Nothing an agent needs to invoke or interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the question must be a single plain question phrased in the customer's words, illustrated by examples that define scope. It does not elaborate on domain formatting, though "verified business" clarifies it identifies the business.

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

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

The description opens with a specific verb and resource ("Ask one plain question about a verified business") and immediately grounds it with two concrete example questions. It is clearly distinguishable from siblings like lookup_business or list_business_offerings, which are named as different operations.

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 exactly when this tool applies (plain factual questions about a business) and when it does not: businesses that don't answer here "point to list_business_offerings and lookup_business instead," and prices, bookings and orders are routed to list_business_offerings, place_order and request_quote. Alternatives and their selecting conditions are explicit.

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, and non-destructive behavior, so the safety profile is covered. The description adds meaningful domain behavior beyond that: tokens are not money, cannot be cashed out or transferred, are limited to the issuing business, and memberships return only valid/invalid rather than a balance.

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 and result, and each subsequent sentence adds return-shape or constraint information rather than filler. It is somewhat dense but nothing is truly redundant.

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

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

With no output schema, the description carries the full burden of explaining returns and does so thoroughly: balance_cents, balance_hours, balance_points, reads_as formatting, and the valid/invalid membership case. An agent has everything needed to interpret 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 100% for the single 'code' parameter, so the schema already documents type and format. The description adds only human context ('the code printed on the card'), matching the baseline 3 where the 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?

States a specific action (return the remaining value) and resource (a closed-loop token: gift card, prepaid hours, membership, or points balance) and names the input (the printed code). It clearly distinguishes itself from siblings like lookup_business or list_business_offerings, which inspect the business rather than a token.

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 usage via 'Takes the code printed on the card' but never states when to choose this tool over alternatives or when not to use it. No sibling is named or excluded, so the agent must infer routing from the tool name and purpose alone.

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, non-destructive, closed-world behavior, and the description adds genuinely new context: results capped at 10, ordered by word-match closeness then name, no paid ranking, only owner-verified Orbylon businesses are eligible, and the exact fields each result returns.

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 examples are front-loaded, and nearly every sentence carries distinct information (ranking, coverage limits, result fields, next-tool routing, test city). It is one dense run-on paragraph with some redundancy ("Both are required" duplicates the schema), which slightly hurts scannability.

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, and the description compensates by enumerating the result fields, the maximum result count, ordering rules, and eligibility constraints, plus the tool to call next for each item type. An agent has everything needed to invoke and interpret the call.

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 baseline is 3; the description adds concrete examples that clarify the intended granularity of each field ("espresso beans"/"Montreal", "plumber"/"H2X"). It restates that both are required, which the schema already encodes, so the lift is modest.

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 with scope: find businesses selling what the customer needs in a named place, with two concrete examples. It is clearly distinguishable from lookup_business and list_business_offerings by describing a need+place search over Orbylon-published businesses.

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 worked examples, states both parameters are required, names the test place for fictional data, and routes the agent to the correct follow-up tool per result type (place_order, request_quote, list_business_offerings). It does not explicitly say when NOT to use it versus the sibling lookup_business, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: the conditional pay_url only appears 'when the business takes card payment', and it discloses a privacy boundary (never returns buyer address, email or phone) that no annotation conveys.

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: the returned fields come first, the required inputs next, and the privacy constraint last. The enumeration is dense but each element earns its place by telling the agent what it will receive.

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 correctly carries the burden of describing return values, including the conditional pay_url, and adds an explicit privacy guarantee. It omits failure behavior (not-found or invalid reference) but is otherwise sufficient for a two-parameter read tool whose annotations cover the safety profile.

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 goes slightly beyond the schema by tying 'reference' to its provenance ('the reference the order answer gave') and identifying 'domain' as the business domain, which helps the agent map values from the place_order response into these fields.

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: returns the outcome of an order created by place_order, and enumerates the concrete payload (status, item, quantity, total, paid flag, pay_url). It explicitly anchors itself to the sibling tool place_order, so an agent can distinguish it from request_quote or list_business_offerings immediately.

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 establishes the precondition for use - 'Takes the business domain and the reference the order answer gave' - which tells the agent this is a post-place_order lookup and where the reference comes from. It stops short of naming when to prefer an alternative (e.g. for a quote rather than an order) or what happens if the order is unknown.

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, closed-world, non-destructive, so the safety profile is covered. The description adds genuine behavioral context the annotations don't: prices are exactly as published and never estimated, and price_on_request items are intentionally price-less. It just doesn't note caching/rate behavior, which is minor for a read call.

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 purpose, then structure of the payload, then the price/price_on_request caveat. Sentences are dense but each carries information; the quoted 'Price on request' reproduction is slightly redundant but aids grounding.

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 describing the return shape: owner_provided with business identity, then per-item name, description, integer price in cents, currency and unit. Combined with the parameter schema and annotations, an agent has everything needed to call and interpret it.

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?

One parameter (domain) with 100% schema description coverage, so the schema already documents the domain format and example. The description adds no further semantics about the parameter, which is the correct baseline 3 when the schema does the work.

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: 'Return the machine-readable catalogue a verified business publishes,' with a clear scope (verified business, published catalogue). It doesn't explicitly contrast itself with siblings like lookup_business or find_businesses, though it does name request_quote for the price-on-request case.

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 routing rule: for items with price_on_request, 'ask it with request_quote rather than estimate a number.' That names the alternative and the condition selecting it, but there's no guidance on when to call this at all versus lookup_business or list_business_paid_endpoints.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the returned URL responds with HTTP 402 and Payment-Required terms, payment settles directly to the business, failed calls are never charged, and an empty catalog returns an empty list with a note. These are exactly the behavioral traits an agent needs before invoking.

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 primary return, then the payment behavior and the empty-result case. No padding or repetition, and the ordering follows the agent's decision path.

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 present, the description carries the full burden and does so: it enumerates the returned fields (title, what it does, HTTP method, price, URL), explains the 402 payment flow, the no-charge-on-failure guarantee, and the empty-list edge case. Nothing needed to call or interpret the result 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?

Only one parameter (domain) exists and its schema description already documents it at 100% coverage. The description implies the tool targets a specific business domain but adds no format or validation semantics beyond what the schema 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?

States a concrete verb (return/list) and a well-scoped resource: the priced endpoints a verified business publishes. It is clear this is a read-only enumeration of a business's sellable HTTP endpoints. However, it never names or distinguishes itself from the sibling list_business_offerings, so the agent must infer the boundary between the two.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g. what 'verified' requires), and no routing to alternatives such as list_business_offerings, lookup_business, or request_quote. The description explains what the tool returns but not when an agent should reach for it over its neighbors.

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, so the safety profile is covered; the description adds real value by explaining the negative outcome semantics ("a 'not verified' answer means Orbylon has no proof, not that they are fraudulent"). It does not cover auth requirements or result latency, but for a public read lookup the disclosure is solid and consistent with 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?

Front-loaded with the core result, then the field enumeration, then the usage cue and the caveat — a logical order with no filler sentences. The return-field enumeration is long but earns its place because there is no output schema to carry 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 carries the return-shape burden and does so thoroughly: key type, verification timestamp/method, and the proofs list with slug, signed-at, SHA-256 and verify link, plus the offerings catalogue. Combined with the negative-result caveat, an agent has everything needed to interpret results.

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 parameter already documents its format ("e.g. example.com"); the description only echoes "for a domain" without adding syntax or edge-case meaning. Baseline 3 is correct when the schema carries the parameter semantics.

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 (return the verified identity record for a domain) and enumerates the substantive contents of that record. It is clearly distinct from search-style siblings like find_businesses, but it never names them explicitly, so sibling differentiation is left to inference.

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 this before trusting or transacting with a business" gives a concrete triggering context, which is more than most read tools offer. It stops short of naming the alternative (e.g. check_business_token, find_businesses) or stating when this lookup is not the right call, so it stays below 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 flag it as destructive, non-idempotent and open-world, but the description adds substantial context beyond them: the preview/confirm safety contract, the exact data returned in preview (seller, unit price, total, currency, refund/cancel terms), where the order is routed, that money flows to the business and never to Orbylon, the set of connected payment providers, and the book_url appointment path. This is rich behavioral disclosure that goes well past 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?

Front-loaded correctly: purpose and the two-step flow come first, then routing/payment details. It is dense and contains some run-on sentences (e.g. 'The order goes straight to the business, where it already works: email...'), but nearly every sentence carries actionable information, so little could be 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 destructive, open-world mutation with no output schema, the description is complete enough to call correctly: it covers the mandatory consent flow, the preview return fields, the final-call return fields (reference for get_order_status, pay_url, book_url), and the payment routing. Nothing essential 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 75% and the schema already documents domain, item, item_id, confirm and idempotency_key. The description reinforces the crucial semantics of 'confirm' (re-send same fields, only after agreement) and explains what the non-confirm call returns, which clarifies the required fields. It adds some value but does not compensate for undocumented params like quantity, note, and nested fulfilment fields beyond the object-level description.

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 ('Order an item a verified business publishes') and immediately routes the agent to the sibling discovery tools (list_business_offerings, find_businesses) for finding items. An agent can tell this apart from request_quote, get_order_status, and the lookup tools 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 defines the two-step protocol: first call without 'confirm' placed nothing and previews terms, then a second call with the same fields plus confirm:true only after the customer agreed. This gives unambiguous when-to-use and when-not-to-use (never confirm unprompted) guidance plus the discovery 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?

Annotations only cover readOnly=false, idempotent=false, destructive=false and openWorld=true. The description adds substantial context beyond that: the request is emailed, the business replies directly to the customer, nothing is paid or owed, no wallet is needed, and consent must be obtained from the customer first — all critical behavioral facts 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 dense sentences: eligibility, mechanism, cost/consent constraint, and return value — front-loaded with the eligibility condition and no filler. Each sentence carries a distinct decision-relevant fact.

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?

Despite 12 parameters with no output schema, the description closes the important gaps: it explains the consent gate, that no payment occurs, and that the call returns a reference and status URL. For a write-ish, open-world tool, 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 description coverage is 100%, so the baseline is 3. The description adds value by tying consent to its legal/UX meaning ('ask the customer first, send consent: true only if they agreed their name, contact and request go to the business') and by framing email/phone as the reply channel, going slightly beyond the field 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?

The description gives a specific verb and resource — request a quote from a verified business — and narrows scope to items marked price_on_request, distinguishing it from place_order (which handles priced items). An agent can tell immediately what the tool produces: an emailed request and a quoted price back to the customer.

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 the use condition clearly (item must be price_on_request: true in list_business_offerings) and names that sibling as the source of the item. It does not explicitly name place_order as the alternative for priced items, so the exclusion from buying flows is left 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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: it discloses the return artifacts (pillar scores, grade, per-check evidence) and warns that the report link is unlisted and opens for anyone holding it, which is a meaningful behavioral detail.

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 outcome front-loaded and the output description following. The parenthetical about the unlisted link is slightly digressive but earns its place by warning about shareability.

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

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

With no output schema, the description carries the burden of explaining return values and does so adequately (pillar scores, grade, per-check evidence, report link). Combined with rich annotations and full schema coverage, an agent has enough to call it correctly, though usage sequencing remains 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 description coverage is 100% and there is only one parameter (url) with an example format in the schema. The description adds no syntax, format, or constraint 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 gives a concrete verb (scan) and resource (business website) and states the outcome precisely: whether AI agents can 'find, trust, and pay it.' It never names a sibling, so differentiation from tools like check_business_token or lookup_business is left to inference, which keeps it just short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the eight sibling tools. A brief note such as 'use before place_order or after lookup_business' would be needed, since the purpose alone leaves the agent guessing about sequencing.

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