Egonex

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

Annotations only declare safety flags (readOnlyHint=false, idempotentHint=false), so the description carries the real behavioral burden and does so richly: response varies by whether seller.answers_questions is true, price negotiation may yield a deal valid 24 hours for one request_order, a 24-hour price hold, decline reason codes (declined, slow_down, handoff, email_required, conversation_stopped), three-declines-per-conversation cutoff, and per-minute/per-day rate limits. It also warns that a seller's reply to an escalated question does not come back through this 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?

The core purpose and the sibling distinction are front-loaded, and nearly every clause carries unique operational information (rate limits, deal terms, stop conditions). However, it is a dense single block mixing behavioral rules, error reasons, and negotiation mechanics without structural separation, which makes it harder to scan than it needs to be.

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

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

An output schema exists, yet the description still maps the meaningful response shapes an agent must branch on — inline answer, deal object, 'seller answers in chat,' and the terminal reason codes. For a non-idempotent tool with negotiation and rate-limit side effects, nothing critical to correct invocation appears 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 operational meaning: conversation_id exists so 'Ego sees the earlier questions and answers,' and it ties deal.id forward to request_order. It does not restate the offer_id sourcing rule (already in schema) or the 500-character limit, but the added conversational continuity semantics justify going above 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?

Opens with a specific verb and resource — 'Ask one question about a listing' — and immediately scopes what questions are appropriate (availability, condition, timing, location, sizes, delivery/pickup). It also names the sibling it is not: 'To send your question to the seller as your user instead, use message_seller,' so an agent can distinguish it from message_seller without opening either 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 frames the use case as pre-decision ('before your user decides') and gives a concrete follow-up rule: pass conversation_id 'for a follow-up about the same listing.' It also names the alternative path (message_seller) and its selecting condition, plus the branch where the seller has no Ego assistant and 'answers in chat.'

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 and destructiveHint=false, but the description goes far beyond that: for every status it discloses whether anything was charged, ordered or sent, whether a token must be re-obtained, whether to reuse the same token or a new one, and which sibling tool to call next. That is precisely the behavioral context an agent needs to avoid double-charging or re-requesting.

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 purpose is front-loaded in one sentence, but the status list is extremely long and repeats the identical boilerplate sentence about post-placement handling on Egonex four times across statuses. Much of the per-status detail earns its place, yet the duplication and sheer length reduce scannability for an agent that mainly needs the status meaning and next action.

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

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

With an output schema present, return-value structure needn't be explained, and the description instead supplies the semantic meaning of every status plus the next action for each. For a one-parameter read tool with rich annotations, nothing an agent needs in order to call 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% and the single parameter's schema description already says 'The id returned by request_order or message_seller.' The prose adds no syntax, format, or provenance detail beyond that, so the baseline 3 for a fully documented schema 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 opening sentence names the specific verb (check), the resource (a request made with request_order or message_seller), and what is returned (the confirm link and the resulting order with title, quantity, amount and deadlines). An agent can distinguish this from search_offers, pay_order, and ask_seller 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?

The description states exactly when to call it (after request_order or message_seller) and, per status, what to do next and what not to do — e.g. 'Don't call pay_order while it shows this; check back later' and repeated instructions that post-placement order handling happens on Egonex, not through these tools. Exclusions and alternatives are explicit rather than implied.

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 (which only say it is a non-destructive mutation), the description discloses the confirm_url gate, that nothing is delivered until the user opens it, that no Egonex account is needed on either side, where the message lands, how the reply reaches a non-account buyer, and that the agent never sees the reply. That is unusually rich behavioral context; it only stops short of stating rate limits or delivery latency.

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 action and its scope are front-loaded, and most sentences carry distinct information (confirmation gate, account-free path, reply routing, follow-up tool). It is dense but a couple of clauses, such as the parenthetical reply-by-email note, could be tightened 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?

For a mutation tool with an output schema present, the description covers the confirmation prerequisite, the account requirements, the delivery path, and the follow-up verification step via check_request. An agent has everything needed to call it correctly and to explain the outcome to its user.

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 for `message` by enumerating the acceptable intents (unanswered question, custom request, restock inquiry) and clarifies the 'as your user' framing that gives `agent_name` its purpose.

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 opening sentence names a specific verb and resource ('Send a message to the seller of a listing as your user') and immediately scopes what kind of message. It is clearly distinguishable from ask_seller and check_request, which are named explicitly later.

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 the three triggering cases (a question Ego couldn't answer, a custom request, a sold-out listing) and then names both alternatives with their selection conditions: ask_seller for an immediate answer from the seller's assistant, and check_request to confirm sending.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description is consistent with a real charge. Beyond the annotations it discloses what gets charged (amount × quantity plus sales tax), what is never charged (sold_out, stock_short, seller_not_taking_orders, shipping_address_required, existing account), and the refund-minus-processing-fee outcome if the seller declines after payment.

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 action and the token/amount requirement are front-loaded, which is good. However, the body is a very dense block of conditional error and retry prose with repeated phrasing ('nothing is charged' recurs many times) and no paragraph breaks, which makes it harder to scan than necessary.

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 payment tool with nine parameters, nested shipping_address, annotations, and an output schema, this is complete: it maps result statuses (waiting_for_seller, ready_to_pay, paid, payment_failed, payment_error) to next actions, names error codes, and explains the shipping-address lifecycle. Nothing material for a correct call 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 meaning the schema cannot: the token must cover at least amount × quantity in USD plus tax, shipping_address is required only on the charging call and is locked afterward, and shipping_address_confirmed must reflect a read-back to the user. It does not add much on request_id, quantity or delivery_days 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?

Opening sentence gives a specific verb and resource ('Pay for an order made with request_order without the confirm page') and names the exact mechanism (a Stripe Shared Payment Token the user approved). It explicitly separates this tool from request_order, check_request and the Egonex confirm page, so an agent knows when this is the charging path.

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 when to call (only after the user agreed to the purchase and terms), the seller-confirms-first sequencing (call again with the same request_id and buyer_email once check_request shows ready_to_pay), and the alternatives (user pays via confirm_url or the emailed link). It also gives explicit do-not-call guidance: don't retry while check_request shows payment_in_progress.

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 real safety signal beyond destructiveHint=false, the description carries the burden well: nothing is ordered or charged until the user confirms, no Egonex account is required, payment runs through Stripe, shipping address is captured at payment time, and the human-in-the-loop confirm_url flow is spelled out. This is consistent with readOnlyHint=false and idempotentHint=false.

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

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

Front-loaded with the action and its key consequence (nothing charged until confirmation), then flows into parameter guidance, follow-up, and the failure case. Dense but nearly every sentence carries operational value; only the Stripe parenthetical feels slightly incidental.

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 an output schema exists, return values would not need explaining, yet the description still flags the critical confirm_url artifact an agent must surface to its user. It also covers the error path and the next tool to call, leaving no operational gap for a mutation tool with a human-confirmation step.

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 genuine meaning for note (dates, quantity, size, delivery/pickup area) beyond the schema's example. It does not elaborate on deal_id or agent_name, leaving those to the schema, so it is short of 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?

States a specific verb and resource with scope: "Start an order for one listing on your user's behalf." It immediately distinguishes itself from pay_order and check_request by naming them as separate steps (confirming/paying happens on Egonex; status is checked via check_request).

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

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

Explicit routing: use note for what the seller must know, use check_request with the returned id to follow up, and use ask_seller when a listing is unavailable. It also names the exclusion condition (sold-out or seller not accepting orders) and its error code listing_unavailable.

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 read-only and non-destructive annotations, it discloses non-obvious behavior including sold-out exclusion, relevance and review-based ranking, translation and query rewriting, empty-result fallbacks, location-based inclusion, and the city_unknown caution. It also states that no account or API key is needed and clarifies that seller trust badges are assigned by Egonex rather than sellers.

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 purpose is front-loaded and the category bullets aid scanning, but the definition then becomes an extremely long, dense paragraph covering output fields, ranking rules, seller badges, and review thresholds. Much of this repeats structured fields or is unnecessary given the output schema, burying the most actionable invocation advice.

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 complex ten-parameter search tool, the definition more than adequately covers query construction, language handling, geography, storefronts, ranking, empty results, availability, authentication, and result-recommendation practices. The rich input and output schemas cover the remaining structural details, leaving only minor workflow-routing and pagination gaps.

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?

Although the schema already documents most parameters and the description repeats substantial query and city guidance, it adds useful semantics such as multilingual translation, rewrite triggers, filler and short-word exclusions, unused_words, and category/store no-match behavior. The remaining additions are mostly elaboration rather than essential new parameter meaning, and limit/offset receive no explicit explanation.

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 opening sentence gives a specific verb, resource, and scope: searching Egonex listings from individuals selling goods and services. The examples make the discovery role clear and readily distinguish it from the messaging, ordering, and payment siblings.

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

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

It explicitly says to use the tool when the user wants to buy, hire, book, rent, or commission something from a person, and adds guidance for storefront searches and recommending listing URLs. However, it does not clearly position the tool within the sibling workflow or state when to switch to ask_seller, request_order, or pay_order.

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