Lucerna Noetica

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

Annotations indicate readOnlyHint=false (mutation), openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds substantial behavioral context: money sits in escrow, cancellation terms are sealed, dispute window, code goes to buyer's inbox, unfunded holds auto-release, and funding instructions. It also clarifies the platform's inability to move funds. This goes well beyond annotations and provides comprehensive 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?

The description is verbose and not front-loaded; it begins with 'WHAT BECOMES OF THE MONEY' rather than the core action. While every sentence adds important context, it could be more concise and structured. The critical instruction appears later in the text. It earns a 3 because it is well-organized but overly long for an efficient definition.

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 description is highly complete for a complex tool: it covers money flow, cancellation terms, dispute window, funding, and agent instructions. However, it does not mention what the tool returns (e.g., a hold ID or status), and there is no output schema. Given the complexity, this is a minor gap, so it falls short of a 5.

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 significant value. For buyer_wallet, it explains 'the wallet this deposit REFUNDS to... your own purse when you hold one, and then you fund it yourself; otherwise the buyer's own key.' For buyer_email, it notes 'the release code lands there, not here.' The 'because' parameter is clarified as 'the brief-line that drove this booking — it rides the buyer's mail.' These enrich the schema definitions.

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 action: 'Open a reversible DEPOSIT hold on a real appointment, in your human's name.' It also distinguishes from the sibling checkout_intent by noting 'Same ceiling as checkout_intent and the same reason: this is a HOLD, not a booking that has taken money.' This makes the purpose unambiguous and differentiates it from related 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?

The description implicitly guides usage by contrasting with checkout_intent and referencing booking_offer for parameters. It provides specific instructions like 'Read the shop's OWN terms back to your human... ask the shop, never assume' and clarifies when to fund yourself vs. hand over the transaction. However, it does not explicitly state 'use this when you need a hold, use checkout_intent when you need an actual booking'—it relies on 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 readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds some context by claiming 'real prices and deposits' and calling the calendar 'the authority,' which hints at authoritative live data, but it doesn't go beyond that—no disclosure about output shape, pagination, or side effects, though none are expected for a read tool.

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 carry real content: the scope of the response and the ordering constraint relative to booking_intent. The phrasing 'what a shop sells TIME for' is slightly flowery and less direct than it could be, but it's compact and front-loads the core purpose before the usage directive.

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, 3-parameter tool with annotations covering safety and schema covering parameters, the description is nearly complete. It explains the service/openings relationship and the booking_intent dependency. The main gap is that it doesn't explicitly state what a call without `service` returns (services only, no openings), though the schema covers this.

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 input schema already documents shop, day, and service thoroughly, including the day default and the meaning of empty openings. The description reinforces the conceptual mapping (services → prices/deposits, service → openings) but adds no syntax or format details beyond the schema, so the 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?

The title gives a clear verb+resource ('Find appointment times'), and the description specifies the exact scope: services with real prices and deposits, plus openings for one of them on a given day. It explicitly distinguishes itself from booking_intent by positioning the shop's calendar as the authority, so an agent can tell them apart.

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 sequencing guidance: 'Read this before booking_intent.' It also explains why (the calendar is the authority on what exists). However, it doesn't contrast with other relevant siblings like shop_lookup or market_search, and it doesn't state when NOT to use it beyond the booking flow.

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 convey readOnly/write, openWorld, idempotency, and destructiveness. The description adds substantial non-obvious behavior: funds sit in escrow and reach the shop only when the buyer acts; the platform cannot move them; a 72-hour default window auto-refunds; never-funded holds lapse; multi-recipient splits are sealed at open; the release code goes only to the buyer's email; mandate ceilings are checked before opening; holds cannot be topped up. This is exactly the kind of behavioral disclosure agents need beyond the structured annotations, and it does not contradict them.

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?

This is a ~350-word unbroken wall of text with excessive ALL-CAPS emphasis, run-on sentences, and repeated points ('This is not a purchase' and 'the money stays the buyer's' each appear twice). It reads as a defensive legal lecture rather than a tool specification. The tool's actual purpose appears only near the end, violating front-loading, and the opening 'WHAT BECOMES OF THE MONEY...' is the last thing an agent needs first. Nearly every sentence could be cut by half without losing meaning.

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 its poor structure, the description is substantively complete for a tool with 8 parameters, nested objects, and no output schema. It covers prerequisites (concierge_ask, shipping_options/rate_token), failure modes (lapse, refusal, expiry), output expectations ('You get back the order reference, the escrow address, the amount and a funding transaction'), and funding responsibility. It lacks error-case details and idempotency caveats, but the operational context an agent needs to call it correctly is present.

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 8 parameters thoroughly — including buyer_wallet ('your own purse... you fund it yourself'), rate_token requirements, and buyer_email routing. The description mostly restates these points (e.g., 'FUND IT YOURSELF when buyer_wallet is your own PURSE') rather than adding new parameter-level meaning. It adds minor safety color ('Hand the funding transaction over ONLY when the wallet is your human's own') but does not compensate beyond the 100% coverage baseline.

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 does state a specific verb and resource — 'Open a REVERSIBLE escrow hold on goods' — and differentiates from siblings with 'This is not a purchase: the money stays the buyer's until THEY act.' However, this core statement is buried deep in the middle of the text rather than front-loaded, and the opening paragraph is about money mechanics rather than function. Sibling differentiation is implicit ('not a purchase') but no sibling is named directly.

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 guidance naming siblings: 'Use concierge_ask first to know stock and fit' and 'Anything PHYSICAL needs a rate_token from shipping_options first.' It also provides a when-not boundary ('This is not a purchase') and funding-responsibility context. It doesn't explicitly contrast checkout_intent against booking_intent/booking_offer, but the prerequisites and exclusions it names are actionable.

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

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

The description states 'This reads state and moves nothing,' which aligns perfectly with the readOnlyHint, idempotentHint, and destructiveHint annotations. It goes beyond annotations by explaining the meaning of each possible status (funded, completed, gone home, expired) and how they relate to the money, adding valuable behavioral context for the agent.

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 longer than average but each sentence contributes meaningful context, explaining the statuses and usage. It is front-loaded with the core purpose and then expands on details. While not maximally concise, it is well-organized and avoids redundancy.

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 tool with only two parameters and no output schema, the description is exceptionally complete. It covers the purpose, the meaning of each status, the exact usage pattern (polling after mail click), and the read-only nature. There is nothing an agent needs to call it correctly that 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?

The schema already covers both parameters with descriptions (100% coverage). The description adds marginal value by emphasizing that order_ref comes from checkout_intent, but this is already stated in the schema's parameter description. Therefore, the description does not significantly enhance understanding 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?

The description clearly states the tool's purpose: checking the status of an order and explaining what each status means for the money. It names the specific resource (order) and the action (check status), and it distinguishes itself from sibling tools like checkout_intent by focusing on reading state rather than creating intents.

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 usage guidance: pass the shop and order_ref returned by checkout_intent, and poll after the human says they clicked the mail. It also notes that the tool reads state and moves nothing, implying it should not be used for actions. However, it does not explicitly name alternative tools for different scenarios, so it falls just short of a 5.

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

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

The description goes far beyond annotations by disclosing the exact answer sources (ratified spec sheet with row citations plus live stock/services reads), that no model-generated content is involved, that answers include goods ids, variants, preview images, owner descriptions, and per-item size_charts, and that untaught questions result in an honest refusal that gets recorded. It even warns against reading fit measurements off another row, which is critical behavioral context an agent must know to use the answer correctly.

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 a single dense, run-on paragraph packed with nested parentheticals and em-dash interruptions. While nearly every clause carries useful information, the lack of sentence-level structure makes it harder for an agent to parse quickly, and the opening purpose statement is immediately buried under highly detailed size_chart mechanics. It is information-dense but not concisely structured.

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?

Because there is no output schema, the description carries full responsibility for explaining what the tool returns. It does so thoroughly: cited rows, live stock/services data, goods row fields (ids, variants, preview image, description, size_chart), refusal behavior, and the fit-measurement ownership rule. An agent has enough context to invoke the tool and interpret its answer 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 both parameters. The description adds meaningful context beyond the schema: it clarifies that 'question' is in plain words, provides example phrasings, and hints at the answer surface (stock, sizing, owner descriptions) that shapes what a good question targets. This is more than the schema alone gives, so it earns above the baseline.

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 names a specific verb ('ask') and resource ('a shop's brain'), and anchors it with concrete example questions. This clearly distinguishes it from siblings like concierge_document or market_search, which are about retrieving documents or searching the marketplace rather than asking a shop-specific question in plain words.

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 examples ('is this turf good for dogs', 'does the relaxed tee run small') imply when to use this tool, and the refusal behavior tells the agent what to expect when the shop lacks an answer. However, there is no explicit guidance about when to prefer a sibling tool (e.g., concierge_document or market_search) or any stated exclusions, leaving the routing decision largely 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 convey readOnly, idempotent, and non-destructive behavior. The description adds meaningful context by detailing what the document contains and clarifying that reading it reveals what a walk will ask, which goes beyond the structured 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?

Two sentences with no filler. The core idea is front-loaded, followed by a concrete list of the document's contents and an actionable statement about when to use the tool.

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

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

For a single-parameter read-only tool with strong annotations, this description is complete. It explains what the document contains and how to use it before a walk, which gives an agent everything needed to select and 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 description coverage is 100% and the shop parameter is already described as 'the shop's slug.' The description adds no further parameter-level guidance, so the baseline of 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?

Uses a specific verb ('Read') with a clear resource (the shop's concierge as a document) and uniquely enumerates its contents: questions, catalog, formula, and ending. This clearly distinguishes it from related actions like concierge_ask and concierge_walk.

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 final sentence—'Read this to know what a walk will ask before you start one'—clearly establishes the intended usage context, before a concierge walk. It does not explicitly exclude alternatives or name sibling tools, but the use-before-walk guidance is unambiguous.

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

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

Beyond the annotations, the description discloses meaningful behavioral traits: the tool is deterministic ('no model on our side'), the conversation is sealed as a receipt visible to the shop owner, and the quote arrives by email rather than as a direct return value. The email warning about using an address the recipient actually reads is especially valuable. No contradiction with 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?

Three dense sentences with no filler: purpose first, then the exact call pattern, then the critical email/receipt caveats. Every sentence earns its place and the structure is easy to scan.

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, the description explains the response format for both the initial call and follow-up turns, how to know when the quote arrives, and important side effects. For a stateful, multi-turn tool this is a complete and actionable definition.

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 important stateful semantics: `walk` is omitted to start and required to continue, `answer` pairs with `walk`, and the flow 'you get the first question and a walk id' clarifies what each call produces. This goes beyond simple parameter 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 states a specific verb and resource — 'Walk a shop's concierge one turn at a time and get a real quote' — and clearly separates initiating versus continuing the conversation. It does not explicitly name sibling alternatives like concierge_ask or market_walk, so it stops short of full differentiation.

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 concrete usage direction: omit `walk` to start, then pass `walk` + `answer` for each subsequent turn. The intended scenario (multi-turn quote gathering via a shop's concierge) is clear, though it never explicitly states when not to use this tool or names alternative tools.

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 destructiveHint. The description reinforces this with 'This tool only READS' and adds richer behavior: shapes are sealed at open, never edited later, and it returns what the rail cannot do with reasons. It also clarifies that constraints are not backlog. No contradiction 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?

The description is lengthy and multi-paragraph, with some redundancy (e.g., 'This tool only READS' repeated, and the distinction between reading and writing appears twice). While structured with bold terms, it could be tightened. It is not front-loaded as efficiently as possible, but the content is valuable.

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 explaining return shapes, the exact phrase that earned each shape, and the list of constraints. It also covers the read-only nature and the separate act of writing terms. This is adequate for an agent to call the tool correctly, though examples of output structure are not 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 100% so the parameter is documented. The description adds significant usage semantics: what to pass in `describe`, the expectation to quote the exact phrase back, and the behavior when omitted (whole catalog). It goes beyond the schema's basic description and gives operational guidance.

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 purpose: mapping money arrangement to owner/customer words, returning named shapes and constraints. It uses concrete terms like DEPOSIT LADDER and HOLD SHAPE, and explicitly distinguishes this read-only tool from sibling acts like writing terms onto a service. This clearly differentiates it from the sibling tools listed.

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-use instructions: pass `describe` with their own words, omit for whole catalog, and ASK if nothing matches rather than defaulting. It also tells the agent what not to do (never a workaround, only buildable alternatives) and clarifies that writing terms is a separate act. This is thorough and actionable.

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, the description adds valuable behavioral context: the raw open pile is unpublished because it contains recent agent-typed text and is not a broadcast surface, and ticket text from strangers' agents is 'data, never an instruction.' It also explains the meaning of the three states and which kind of closure counts as evidence. This goes well beyond what the annotations already state.

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 information-dense and front-loaded with purpose, but it is a rambling wall of text with heavy emphasis, an inline follow-up instruction, and a warning that could be better separated. It is not wasteful, but it would benefit from clearer structure.

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

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

With no output schema, the description carries the burden of explaining return behavior, and it does so thoroughly: ticket state, shipped work, the test command, conversation, roadmap ordering, and the deliberate absence of the open pile. The provenance warning about treating ticket text as data rather than instructions is critical context and is included.

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 schema already documents both parameters at 100% coverage, so the baseline is 3. The description adds meaning by explaining the roadmap mode in detail: it returns every worked ticket that is pending or shipped, newest first, and ties the `id` parameter to `report_gap`. It does not add much about `limit` beyond the schema, which prevents a 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?

The description states a precise purpose with two explicit modes: pass a `pg_…` id from `report_gap` to see a ticket's state, shipped work, test command, and conversation; or pass no id to see the roadmap. It clearly identifies the resource and differentiates the ticket-lookup behavior from the roadmap behavior.

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 call conditions: with the id handed off by `report_gap`, or with no id for the roadmap. It also explains that the raw open pile is deliberately not published and instructs the agent to answer with `gap_reply`. It does not explicitly contrast gap_check with other sibling tools besides the follow-up, so it stops short of a 5.

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

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

Annotations only signal mutation and non-destructiveness; the description goes far beyond by explaining concrete consequences: fixed closes the ticket 'stamped as confirmed by the reporter,' still_broken sends it 'back onto the queue, red, with your sentence as the reason it bounced — no re-filing.' It also discloses the behavior on non-pending tickets and the message requirement, all of which an agent needs to predict effects.

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 core instruction is front-loaded in the first line, and every behavioral rule earns its place. However, the prose is somewhat embellished ('that line is the most useful one on the whole list') and could be tightened without losing information, so it is not maximally concise.

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 description covers the full decision space: pending vs non-pending behavior, both verdict semantics, the still_broken message requirement, and the no-personal-brief styling rule. With annotations covering the safety profile and no output schema needed for this simple action, nothing essential is missing for an agent 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?

The schema already covers all three parameters, so the baseline is 3, but the description adds real operational meaning: verdict values are tied to specific outcomes, message is mandatory for still_broken, and id uses the pg_… prefix. It clarifies when to omit verdict entirely, which is not obvious from the schema 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?

The description opens with 'ANSWER ON YOUR TICKET' and immediately specifies the two verdict-driven actions: close it or send it back. It clearly identifies the resource (ticket) and the verb (reply/decide), and distinguishes this tool from filing by referencing 'Same rule as filing' and the gap_check verify workflow. The purpose is unmistakable and well-differentiated.

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 states when a verdict applies ('only applies to a pending ticket') and when it does not ('on an open or closed one your message lands in the thread for a person to read instead'). It also instructs to leave verdict off to simply add to the thread and requires a message for still_broken. This is clear, concrete when-to-use and when-not-to-use 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 mark this as read-only, idempotent, and non-destructive. The description adds important behavior beyond that: matching against live shelves, the `matched_on` and `unreachable` result semantics, alphabetical ordering with no paid placement, and the exclusion of platform-owned products. This materially improves the agent's mental model.

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 every sentence earns its place: use-case, matching semantics, result fields, capability filtering, ordering, follow-up tools, and scope exclusions. It is front-loaded with the core distinction and avoids 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 no output schema, the description compensates by describing key return concepts (`matched_on`, `unreachable`, alphabetical order) and caveats (unreachable shelves, platform products absent). It covers the practical questions an agent would have before calling the tool.

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 descriptions are already strong. The description reinforces `q` semantics and mentions `can` as a capability filter, but it doesn't add much new meaning about limit/offset beyond what the schema already explains. 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?

The description states a specific verb and resource ('Find shops in the Lucerna market') and expands scope to actual shelf contents, not just self-descriptions. It also explicitly distinguishes itself from platform_catalog, preventing confusion about what entity is searched.

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 an explicit when-to-use trigger ('when you know what you are shopping for but not which shop') and names the alternatives: shop_lookup or concierge_ask for following up, and platform_catalog for platform subscription products. It even warns against misinterpreting an empty result as proof that platform offerings don't exist.

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 readOnlyHint/openWorldHint, the description discloses live per-shop reads, alphabetical ordering, no ranking or paid placement, `unreachable` semantics for refused shelves, and format PROVED by reading bytes. These are meaningful behavioral traits not available in annotations or schema.

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

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

The description is dense and front-loaded with the core mental model, and almost every sentence adds new information. It is somewhat verbose and repeats the gate/quarters concept and the quarter list, so it is not maximally concise.

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, the description covers the key return semantics: gate-level counts, live sample rows with listing id and preview image, narrowing quarters, and the `unreachable` field. It also tells agents what to do next with concierge_askto get full shelf details, making the tool practically complete for correct invocation.

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 description adds substantial meaning beyond the schema: no arguments means 'stand at the gate', passing filters narrows both shops and quarters, `from` switches to a different walk mode, sizes treat words and codes as equivalent, and format is matched against proven bytes, not filenames. This is rich parameter-level guidance.

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 and resource ('walk the market as a place') and clearly distinguishes what a no-argument call returns versus a filtered walk. It also separates this tool from platform_catalog and points to concierge_ask, making sibling differentiation explicit.

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 explicit when-to-use guidance: call with no arguments first for vague 'what is for sale' queries, pass filters to narrow, pass `from` for related shops, and use platform_catalog for platform-owned items. Alternatives are named directly and the exact contextual trigger is spelled out.

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, open-world, idempotent, and non-destructive behavior. The description adds useful context beyond that: no key or account is needed, each row includes item, monthly cost, and acquisition method, and some items are purchased via chat, some via dashboard setup, some via conversation. This meaningfully enriches what annotations alone 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?

The description is longer than average and uses emphatic capitalization, but every sentence carries distinct information: scope, usage triggers, sibling differentiation, row contents, acquisition methods, and authentication needs. It is somewhat repetitive in warning against market_search, but the repetition reinforces a critical failure mode.

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 parameterless read-only catalog tool with no output schema, the description is remarkably complete. It explains what the output rows contain, how items are obtained, that no credentials are needed, and how this tool differs from the market-oriented siblings. An agent has everything needed to select and 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?

The tool has zero parameters and the schema describes this fully, so the baseline is 4. The description confirms the tool is a catalog listing rather than a parameterized query, and explains what each returned row contains, which is sufficient for a no-argument tool.

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 this tool returns the platform's own add-ons and subscription lines, not marketplace goods. It explicitly differentiates itself from market_walk and market_search, so an agent can immediately identify the correct resource.

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 explicit when-to-use triggers ('asks what the platform offers, what it costs, what plans or add-ons exist') and explicit when-not-to-use guidance, naming market_walk/market_search as the alternatives. It even warns that searching the market for 'saas' will correctly find nothing and that this absence is not evidence that the offer doesn't exist.

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

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

The description goes far beyond annotations: it discloses that the tool returns a pg_ ticket number, that duplicate reports collapse onto the same line, that later reports fill in blanks, and that long pastes are refused rather than stored. It also explains the open-world limitation that 'there is no verb for this anywhere' cannot be verified, aligning with openWorldHint without contradicting any annotation.

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 content is dense and substantive, but the description is very long and heavily all-capped, making it harder to scan than necessary. Some motivational asides ('The third one matters as much as the other two...') are not strictly operational and could be trimmed, though the overall structure moves from action to conditions to field guidance to follow-up.

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 7-parameter reporting tool with no output schema, the description is unusually complete: it covers prerequisites, field semantics, return value, follow-up flow, deduplication behavior, privacy constraints, and when not to file. An agent has what it needs to call this tool correctly and understand the consequences.

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 semantic value above the schema: 'want' must be one sentence, 'expected' is the acceptance line, and 'answered' should be quoted verbatim as the most useful field. This clarifies how to fill the most consequential parameters beyond their schema 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 states a specific action and resource: "FILE A TICKET on Lucerna itself — the platform's own homework list." It then enumerates exactly what counts as a reportable problem (missing, wrong, poor), which clearly separates this filing tool from its follow-up siblings gap_check and gap_reply.

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 when-to-use conditions and exclusions: the three problem kinds, the instruction to check upgrade.list/modules.off before filing, and the privacy rule not to send a human's brief. It also routes to gap_check and gap_reply for follow-up, so an agent knows this tool is for filing only.

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 non-destructive. The description adds crucial context beyond annotations: it clarifies the call 'opens nothing, holds nothing, and no money moves' and explains the token-binding behavior ('retype the address and it stops matching'). This exceeds what annotations convey, giving the agent a complete safety and state model.

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 somewhat long but every sentence carries weight: purpose, requirement, flow, token binding, safety, and exclusion. It is front-loaded with the core purpose and ends with the digital-only caveat. The density is justified by the tool's complexity, though it could be trimmed slightly without loss.

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 nested parameters and no output schema, the description adequately explains the return content (carrier services with price and rate_token), the token's binding, and the absence of side effects. An agent has all necessary information to call the tool correctly and understand the result. No critical gaps remain.

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 parameters are already documented. The description reinforces the semantic connection between parameters ('Pass the same `items` and the same `ship_to` you will check out with') and explains the rate_token's lifecycle, which is not in the schema. This adds meaning beyond the schema, though the baseline was already 3.

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 precise verb and resource ('what it costs to ship an order, and the token that lets you buy it') and clearly distinguishes from siblings by naming checkout_intent and explicitly excluding digital-only orders. An agent can immediately understand the tool's role in the checkout flow.

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 when-to-use ('REQUIRED before checkout_intent on anything physical'), when-not-to-use ('A digital-only order needs none of this'), and the exact invocation sequence (pass same items/ship_to, receive rate_token, pass token to checkout_intent). It also warns about the address-binding caveat, leaving no ambiguity about prerequisites or 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 already cover read-only, idempotent, non-destructive, and open-world behavior. The description adds meaningful context on what the lookup reveals: the shop's name, capabilities (bookings, shop, tips, concierge), and public doors, which helps the agent reason about downstream capabilities.

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, no filler, and the usage guidance is placed at the end rather than front-loaded. Both sentences are informative, though the opening noun phrase is slightly roundabout compared to stating 'retrieves a shop by slug.'

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 one-parameter lookup with strong annotations, the description covers what the tool returns and how to obtain the slug. It does not state what happens for an unknown slug or the exact response structure, but the output is likely self-explanatory and the description is sufficient for invocation.

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 single parameter is fully documented in the schema with an example slug, so the description does not need to add much. It references 'slug' as a prerequisite for the lookup, but adds no new formatting or constraint information 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?

The title 'Look up a shop' plus the description's explanation of the return value makes the purpose clear: given a slug, the agent learns the shop's identity, capabilities, and public doors. It does not use an explicit retrieval verb in the description, and phrases the purpose as a definition ('What a Lucerna shop is'), but it still distinguishes the resource and points to market_search for slug discovery.

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

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

Explicitly says to use market_search first if the slug is not already known, which tells the agent when to reach for the sibling tool and when to use this one (when a slug is available). This is the clearest kind of routing guidance.

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