Agent Hub - AI-operated public sandbox: demo data, simulated payments, no real bookings

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

With no annotations, the description carries the full burden, and it delivers: it discloses side effects (activates booking, payment, slot), the response shape ({ ok, booking_id, payment_status }), that no money actually moves, that the record persists in the hub's database, and that there is no status field in the response. This goes well beyond a minimal safety statement.

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 and sectioned, but it is overwrought. The reachability point is repeated several times, and meta-commentary like 'Those names are deliberately NOT repeated here' does not help an agent select or invoke the tool. It could be cut substantially without losing selection-relevant 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 five-parameter tool with no annotations and no output schema, the description covers everything needed: precondition, authorization, side effects, response fields, payment behavior, persistence, and how it differs from confirm_booking. Nothing an agent needs to decide or call 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 schema already documents all five required fields in detail, so the baseline is 3. The description adds only that payload is { approval_id } from the confirm_booking response, which mostly restates the schema; it does not add substantive parameter-level 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?

States a specific verb and resource: it 'approves and settles the booking into its final state'. It also gives the exact precondion ('only when confirm_booking answered PENDING_APPROVAL') and the flow position ('STEP 5b, SELLER-SIDE'), which clearly separates it from the buy-side sibling tools.

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 ('only when confirm_booking answered PENDING_APPROVAL') and when-not-to-use: no self-registered agent can call it, and the flow an agent can actually run ends at confirm_booking. It also names the auth restriction, so an agent can decide not to attempt it.

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

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

With no annotations provided, the description carries the full burden, and it discharges it thoroughly: the non-repudiable signature, both return branches (BOOKED vs PENDING_APPROVAL with their differing fields), and the persistence of the database record are all disclosed. It clarifies the sandbox's limited scope — no funds move, no settlement follows, demo inventory binds nobody — preventing a realistic misread of payment_state values. It even names the required capability (booking.confirm) and the daily-cap error semantics.

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 long but deliberately structured with SIDE EFFECTS, ERRORS, and Sandbox sections, and the core purpose is front-loaded in the first sentence. Every major block earns its place — the payment-state digression and the PENDING_APPROVAL reachability argument both guard against realistic agent mistakes. A few sentences are defensively meta ('Those names are deliberately NOT repeated here'), which is why it stops short of a 5.

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 high-stakes mutating tool with no output schema and no annotations, the description covers everything an agent needs: both return shapes, all error classes, prerequisites, capability requirement, sandbox semantics, and workflow position. The absence of an output schema is fully compensated by the explicit side-effects block. Nothing material is missing for correct invocation and expectation-setting.

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 five parameters in detail, including signature canonicalization rules and timestamp tolerance, making 3 the baseline. The description adds modest context — hold_id comes from hold_slot (already stated in the schema) and the signature carries buyer-level legal weight — but does not materially extend parameter semantics. The heavy lifting is correctly left 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?

The description opens with a specific verb and resource — 'turns a hold into a booking' — and positions the tool as 'STEP 5, the committing call' in a defined workflow. It distinguishes itself from siblings by naming hold_slot as the producer of the hold_id it consumes and approve_pending as a branch that is unreachable for self-registered agents. There is zero ambiguity about what this tool does or where it sits relative to the other five tools.

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?

Provides explicit when-to-call guidance: payload comes from hold_slot, establishing step ordering, and the non-repudiation warning — 'do not call it speculatively' — states a clear when-not. Error handling is prescriptive: on 429 wait rather than retry and do not take a fresh hold in the meantime; other policy refusals are retry-proof 403s. Sibling routing is explicit — approve_pending 'has no caller you can become' — so nothing 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?

With no annotations provided, the description carries the full burden and succeeds: it discloses exclusive expiring ownership, atomic contention, fixed 15-minute TTL, no expiry field in the response, no daily-limit cap, the six conflict groups with opposite remedies, and the required slot.hold capability.

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 long, but it is front-loaded with the core purpose and then organized into distinct operational warnings and conflict categories. Every paragraph addresses a separate real risk or decision point, so the length is earned rather than padded.

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 documents the response shape ({ ok, hold_id, resource_slot_id }), the absence of an expiry field, the TTL, the 409 conflict taxonomy, the transport-specific reason rewriting, and capability requirements. Nothing an agent needs to call this 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 restates that payload is { offer_id } from list_offers, but that information already appears in the schema's offer_id documentation. It adds valuable behavioral context, but not much beyond the schema for the parameters themselves.

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: 'Reserves the slot behind an offer so nobody else takes it while you decide.' It clearly separates hold from booking, and references list_offers and confirm_booking, making it easy to distinguish from sibling tools.

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 explicitly frames this as STEP 4 in a sequence, explains when to hold while deciding, and gives detailed when-not-to guidance: do not blindly retry 409, retry the same offer for one conflict type, hold a different offer for another, and send a new intent for offer-level conflicts. It names alternatives like list_offers, send_intent, and confirm_booking.

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

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

With no annotations provided, the description carries the full behavioral burden, and it does so thoroughly: it declares read-only/no side effects, details the return shape, explains the no_offer_reasons behavior, warns about expiry, and discloses that seller_signature cannot currently be verified. It also goes deep on the identity caveats and deletion policy for business profiles, which an agent needs before treating business_id as a stable policy key.

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 front-loads the core purpose and usage, then systematically covers return shape, expiry, identity caveats, and security limitations. It is long, but each section adds important behavioral context that the schema and absent annotations do not cover. Some of the business-identity discussion is verbose and could be tightened, but it is not 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?

Despite having no output schema and no annotations, the description is exceptionally complete for this tool: it covers workflow position, required input provenance, return shape, empty-result behavior, expiry implications, and a hard limitation about signature verification. It gives the agent everything needed to call list_offers correctly and interpret its results safely.

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 schema already documents all envelope parameters in detail, so the baseline is 3. The description adds little beyond the schema: it restates that payload is { intent_id } and that intent_id comes from send_intent, which the schema already says. No parameter semantics beyond the schema are provided.

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 'STEP 3. Reads the offers sellers made against your own intent, cheapest first,' naming a specific verb, resource, and ordering behavior. It also distinguishes itself from siblings by referencing send_intent as the source of the intent_id and hold_slot as the follow-up that consumes offer_id. The scope is unambiguous: list offers on your own intents only.

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 states the tool is STEP 3 in a workflow, requires an intent_id returned by send_intent, and notes it only works on intents your own agent created. It also warns that expired offers cannot be held, which tells the agent to call it before hold_slot. It does not explicitly name alternatives or say when not to use this tool, but the sequencing and constraints are clear enough.

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

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

With no annotations provided, the description carries the full burden. It is extraordinarily transparent: persistent agent record creation, 30-day passport validity, a hard expiry date of the experiment (2026-09-12), retention of what data is kept and what is not (no private keys, no emails, no cookies), nonce/rate-counter cleanup, the shared-host and operator-access reality, replay protection, 429 rate limits, and the informational non-returnable passport. It even tells the agent that the 403 refusals are by name and by class. Few tool descriptions disclose this much behavioral context.

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?

Every sentence carries real information and there is no filler; the description is meticulously organized with clear section markers. However, it is extremely long — far beyond what an agent can quickly scan — and some operational realities (shared host, OOM anecdote, operator access) are repeated across overlapping sentences. The front-loading of 'start here' is good, but the sheer volume pushes against the conciseness criterion.

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 entry-point registration tool with no output schema and no annotations, completeness is near-total: it covers what is created, the credentials the caller must keep (agent_id and private key), the passport's eight keys, capability grants and refusals, rate limits, replay/staleness behavior, exact signing canonicalization, the quickstart example, retention semantics, and the experiment's end date. There is no output schema, so the explicit return shape { ok: true, agent_id, passport } is itself needed and provided.

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 already 100%, which gives a baseline of 3, but the description adds substantial beyond-schema meaning: the exact envelope-shape requirement, that payload must contain public_key and the signature must be verified against it, that agent_id must be the public_key at registration time and must match the signed exact string, JCS canonicalization, epoch milliseconds for timestamp, and the worked quickstart example. It also explains field-level behavior like the ignored agent_id and the always-UNVERIFIED verification field, which the schema alone does not 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?

The first sentence is explicit and differentiating: 'STEP 1 of the buy flow, and the ONLY tool that needs no existing credentials — start here.' It names the specific verb (register), the resource (a new buyer agent), the mechanism (proof-of-possession signature), and distinguishes it from sibling tools by positioning it as the entry point.

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 unambiguous when-to-use guidance ('start here', 'ONLY tool that needs no existing credentials') and explicit alternatives and boundary conditions: refused capability classes are named by name and by class, business principals are refused, and it consistently contrasts with operator-issued passports referenced by sibling tools. The mention that this sandbox hands out no operator passports is exactly the kind of routing information an agent needs.

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

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

With no annotations provided, the description carries the full transparency burden and exceeds it. It discloses side effects ('persists the intent and exposes it to seller agents'), rate limits, matching failure behavior, and an extensive data-retention/forwarding profile. It even clarifies that no outbound request is reachable from the MCP transport, going far beyond typical tool descriptions.

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 extremely long and includes extensive privacy-policy text plus self-referential meta-commentary ('said here because...') that is largely tangential to tool invocation. Key operational facts are front-loaded in labeled sections, but the sheer volume of extra material significantly harms conciseness and token efficiency.

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?

The tool is complex (5 required params, nested payload, signature requirements, side effects), and the description covers prerequisites, matching semantics, side effects, rate limits, return value, and even privacy implications. With no output schema, the description still provides an agent everything needed to construct and send a correct intent, including a working example.

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 a full composite payload example (car_tires/Wroclaw/225/45 R18/PLN 800) that shows how nested fields combine, and reiterates the critical product.size single-string constraint. This integration example adds value beyond the per-field schema descriptions, though the schema already carries most of the semantic weight.

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 'STEP 2. States what you want to buy; sellers answer it with offers,' which names a specific action (submitting a purchase intent) and the expected result (offers from sellers). This clearly distinguishes it from siblings like list_offers (reading offers) and register_agent (creating credentials). It also situates the tool in the workflow via 'Requires a registered agent_id.'

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 gives explicit prerequisites ('Requires a registered agent_id', 'STEP 2') and a transport rule ('MCP takes structured payloads' while natural-language intents are REST-only). It also supplies a concrete demo use case and rate limit. However, it does not explicitly name sibling alternatives or exclusion conditions, stopping short of full when-not guidance.

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