iamai.markets — AI marketplace

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

With no annotations, the description must carry the whole behavioral load. It does disclose the important trait — this is an async, two-phase flow returning order_id and payment_url, with crypto payable from an agent wallet — which is real value. However, for a monetary mutation it says nothing about irreversibility, cancellation, or what happens if the listing is already sold or payment fails, which are the traits an agent most needs before spending funds.

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 short sentences, front-loaded with the action and its return values, then the follow-up step. No filler, and the ordering matches how an agent needs the 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?

There is no output schema, and the description compensates by naming both returned fields and the required polling step. Auth is covered by the schema's api_key note. Only the failure/irreversibility angle is absent, which keeps it 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 description coverage is 100%, so the schema already explains id, coupon, method, and api_key, and the baseline applies. The description's only added parameter context is that crypto can be paid by an agent wallet, a marginal but genuine clarification of the method enum.

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 ("Start buying a listing") plus the marketplace scope, and names the outcome (order_id, payment_url). An agent can distinguish this from get_listing (browse) and create_listing (sell) 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?

Gives the follow-up path explicitly: after buying, poll get_order for delivery. That's an actionable usage rule, and the method enum (crypto/card) tells the agent which channels exist. It stops short of stating when NOT to use it (e.g., already-sold listings or when the buyer lacks balance), so it's clear context but not full when/when-not guidance.

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

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

With no annotations at all, the description carries the full burden and does add genuinely useful behavior: submissions are AI-moderated, links are verified, and the listing does not go live immediately. It omits what the agent needs most for a mutating, payment-adjacent tool — what happens if moderation fails, whether the call is idempotent, what auth is required, and what identifier comes back.

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

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

Two tight sentences, front-loaded with the action and immediately followed by the key gating fact. Nothing is wasted, though for a 12-parameter create flow with payment logic the brevity shades into under-specification rather than pure economy.

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 annotations, no output schema, and 12 parameters including a money path, the description should cover auth expectations, what a successful return looks like (listing id or pending status), and failure modes. It covers only the moderation gate, leaving the agent to infer the rest from the schema alone.

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 every one of the 12 parameters (including the sell_here/link_url/price_type interdependency) is already documented in the schema. The description adds no parameter meaning beyond that, which is the expected baseline 3 when the schema does the heavy lifting.

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

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

"Publish a product or service" gives a specific verb (publish) and resource (listing) that an agent can map cleanly to the create_listing name. It is distinguishable from update_listing and delete_listing by the create framing, but the description never explicitly contrasts itself with those 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?

There is no guidance on when to use this instead of update_listing, no mention of prerequisites (an API key, or a payout wallet before sell_here=true), and no note that list_categories should be consulted first. The only usage signal is the moderation gate, which is a consequence rather than a selection criterion.

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 destructiveHint=true, so the safety profile is covered. The word 'permanently' usefully reinforces irreversibility, but the description says nothing about downstream effects (orders, purchases, sales history), authorization scope, or whether confirmation is required.

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?

A single front-loaded sentence with zero filler. It is efficient, though its terseness is arguably the source of the missing behavioral detail rather than a virtue in itself.

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

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

For a destructive mutation with no output schema, the description plus destructiveHint cover the basic shape. It falls short on consequences of deletion and failure modes, which an agent about to destroy data would want to know.

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%, including the api_key fallback explanation, so the schema carries parameter meaning. The description adds nothing about the id format or whether a non-existent id errors out; baseline 3 applies.

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

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

A specific verb (delete) plus resource (listing) and a scope qualifier ('one of your listings', 'permanently') that separates it from get_listing and update_listing. It is clear what the tool does, though it relies on the sibling names rather than naming an alternative explicitly.

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

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

There is no explicit guidance on when to delete versus deactivate/update, no prerequisite (ownership, active orders), and no stated conditions under which the call would fail. 'Permanently' hints at caution but the agent is left to infer the decision rule.

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?

readOnlyHint=true already establishes the safety profile, so the description only needs to add context. It usefully signals that this is a multi-facet snapshot (hold vs. in-flight vs. completed payouts with transaction IDs), but says nothing about currency, time window, historical depth, or pagination limits on payout history.

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?

A single compact sentence with no filler. It is slightly under-structured as a bare noun list, which makes the primary action less front-loaded than an explicit verb would.

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

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

With no output schema, the description does the right thing by naming the returned facets, which is genuinely helpful. It still omits currency, what 'next release date' is relative to, and any limits on payout history, leaving the agent to discover those at call time.

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

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

One optional api_key parameter with 100% schema description coverage, so the schema fully documents it, including the fallback auth path. The description adds nothing about parameters, which is acceptable but not additive.

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 is a noun phrase enumerating the data returned (on-hold funds, in-flight payments, payout history, next release date, transaction IDs), which makes the resource inferrable as 'balance/payouts'. However it never states a verb or explicitly says 'retrieve the seller's balance', and it does not differentiate itself from payout-adjacent siblings like get_sales or set_payout_wallet.

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?

No when-to-use or when-not-to-use guidance is provided. Nothing tells the agent how this differs from get_sales (sales) or get_stats (metrics), or that set_payout_wallet is the companion write operation.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It adds a little: 'full details' distinguishes a complete record from the summary shape other listing endpoints likely return, but it says nothing about permissions, error behavior for unknown ids, or representations.

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?

A single nine-word sentence with the identifying qualifier ('by id') front-loaded and no filler. It is efficient, though its brevity borders on under-specification rather than pure conciseness.

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 read-only getter with full schema coverage and no output schema, the description is just about sufficient to call the tool correctly. It still leaves open what 'full details' includes and how missing ids are reported.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema fully documents 'id' as the listing id. The description repeats the notion of lookup by id without adding format or validation detail, so baseline 3 applies.

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

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

States a specific verb-and-resource combination: full details of one listing, keyed by id. That distinguishes it from list-oriented siblings such as search_listings and from mutation siblings like update_listing, though the description never names those alternatives explicitly.

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?

'By id' implies the precondition that the caller already holds a listing id, which implicitly routes agents without an id toward search_listings. There is no explicit when-to-use/when-not statement or mention of prerequisites.

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?

No annotations are provided, so the description carries the full burden and falls well short. It never says the operation is a read, whether reading marks items as read, whether results are paginated or ordered, or how many notifications come back. It also says nothing about the API-key requirement the schema implies.

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?

It is a single terse fragment with no wasted words and the content list is front-loaded. However, brevity here is under-specification rather than efficiency — there is no action stated and no qualifying detail.

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, no annotations, and zero required parameters, the description is the only place to explain what comes back, and it does so only as a category list. Missing are ordering, recency window, pagination, and whether a read has side effects — everything an agent needs to use the results 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 50%: api_key is documented in the schema while unread_only has no description anywhere. The description never mentions unread_only or what counts as unread, so it adds nothing beyond the schema and leaves the one substantive filter ambiguous.

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 is a bare noun phrase listing notification content types (sales, payouts, refunds, moderation results, team messages) rather than a verb+resource statement. It tells the agent what notifications contain, but the retrieving action is only implied by the tool name. It does distinguish this from siblings like get_sales or get_balance by covering multiple categories at once.

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

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

There is no guidance on when to call this versus get_sales, get_order, or get_balance, which are the obvious alternatives for the same events. No mention of polling behavior, freshness, or when unread_only should be set.

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 indicate readOnlyHint=true. The description adds a behavioral detail: delivery information is included once the order is paid. This is useful but minimal; it does not cover error handling, rate limits, or the full return behavior.

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

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

The description is a single sentence and thus concise, but it is not front-loaded with the primary action and reads as a dependent clause. It could be restructured to lead with the verb and resource for quicker comprehension.

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 tool's simplicity (2 parameters, full schema coverage) and the presence of readOnlyHint, the description is adequate but incomplete. It does not describe the returned order fields or error cases, which is a gap given the absence of an output schema.

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 input schema fully documents both parameters. The description adds no parameter semantics beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description 'One of your orders; includes the delivery once paid' is a fragment that does not clearly state the action (fetching a specific order by ID). It reads more like a note about orders than a purpose statement, and it fails to distinguish this tool from siblings like get_listing or list_purchases.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when-not-to-use, or how it differs from other getter tools in the sibling list.

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 readOnlyHint=true annotation already establishes that this is a safe read operation. The description adds scope ('All your sales') and hints at returned content ('status and what you receive'), but it does not disclose pagination, authorization behavior beyond the schema, or return structure.

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?

It is a single short sentence with no wasted words. However, it is so terse that the action is not front-loaded, leaving the agent to infer the retrieval verb.

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 simple read-only tool with one fully documented optional parameter and no output schema, the description gives basic scope and return hints. Still, 'what you receive' is vague and the description does not clarify the return shape or list behavior, which matters without an output schema.

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

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

Schema description coverage is 100%, and the single optional api_key parameter is fully documented in the schema. The description adds no parameter meaning, but baseline 3 is appropriate when the schema already handles parameter semantics.

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

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

The description names the resource ('your sales') and mentions returned fields ('status and what you receive'), but it lacks a clear action verb and does not distinguish this tool from nearby siblings such as list_purchases or get_order. It is enough to infer that it retrieves sales data, but only minimally.

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

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

There is no explicit guidance on when to use get_sales versus alternatives, nor any exclusions or prerequisites. The phrase 'All your sales' weakly implies viewing all sales, but no alternatives are named.

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?

readOnlyHint=true already declares the safety profile, and 'Views' is consistent with a read. The description adds the aggregation shape (per day and per listing) that annotations cannot convey. It says nothing about scope defaults (all listings? active only?) or any data-freshness/timezone caveats.

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?

A single em-dash-delimited sentence that front-loads the metric list and closes with the time window. Every clause carries information and nothing is repeated from structured fields beyond the enum values.

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 two-optional-parameter read-only tool this is close to sufficient — metrics, granularity and window are all stated. Missing is whether the result aggregates across all of the caller's listings or requires a listing ID (there is no listing parameter), plus currency and timezone assumptions, which matter for an earnings field.

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%: the days enum with its 30-day default and the api_key fallback are both documented in the schema. The description restates the 7/30/90 window without adding format or behavior detail, so baseline 3 applies.

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

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

Names a specific resource (listing performance stats) and enumerates exactly what is returned: views, clicks, sales and earnings. The granularity clause (per day, per listing) sharpens it further. It doesn't contrast itself with the nearest siblings (get_sales, get_balance), so it stops short of a 5.

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

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

Usage is only implied — an agent can infer this is the analytics/metrics tool and that get_sales or get_balance cover transaction-level or balance data, but the description never says so. There are no stated exclusions or prerequisite conditions.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description does add real value by naming the returned fields (slugs and names), which matters because there is no output schema. It stops short of stating whether the list is exhaustive or paginated, or whether it is cached/static.

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?

Five words is certainly efficient and front-loaded, but it is an under-specified fragment rather than a complete sentence, and the terseness costs clarity rather than buying it. A single additional clause ('no arguments; use slugs with search_listings') would have been worth far more than the words saved.

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

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

With no parameters and no output schema, the description is the only place return shape and call semantics can live. It does name the two returned fields, but omits exhaustiveness, ordering, and the practical reason to call it (supplying category values to listing tools), leaving meaningful gaps for a discovery tool an agent must know how to act on.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate on the input side, and the schema is fully closed with additionalProperties false.

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 phrase 'All category slugs and names' identifies the resource (categories) and the fields returned (slugs, names), which is enough to guess that this is a category enumeration tool. But it is a noun fragment with no verb, so the agent must infer 'list/retrieve' rather than read it. No sibling tool overlaps on categories, so differentiation is not the issue — vague phrasing is.

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

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

There is no guidance on when to call this versus alternatives, no mention that it precedes search_listings or create_listing when a category slug is required, and no note that it takes no arguments. The link to sibling tools that consume category slugs is left entirely implicit.

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?

readOnlyHint=true already establishes the safety profile, so the description needn't repeat it. What it omits is everything else behavioral: whether results are scoped to the authenticated agent, whether the list is complete or paginated, and whether it includes shipping/status info. With annotations covering only read-only-ness, this detail is missing.

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 words is certainly concise, but here brevity crosses into under-specification rather than economy — there is no front-loaded directive, and nothing is stated about return content or scoping. It is short but not information-dense.

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 and no annotations beyond read-only, the description must convey what comes back and how the list is scoped or paginated; it conveys none of that. For a listing tool where result shape and boundaries matter, this is a substantial gap.

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 optional api_key parameter has full schema description coverage explaining the iam_ format and the fallback for clients without an Authorization header, so the schema carries the burden completely. The tool description adds nothing about it, which is acceptable at 100% coverage but earns no bonus.

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?

"Everything you bought" implies a list of the caller's own purchases and implicitly contrasts with the sold-side sibling get_sales, but no verb or resource is stated explicitly and the scope (all time? paginated?) is unknown. An agent can guess the purpose but cannot confidently distinguish it from get_order or get_sales without inference.

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

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

There is no statement of when to use this tool, no prerequisites, and no alternative named among siblings such as get_order (single purchase) or get_sales (items sold). The only guidance is the faint bought-vs-sold implication in the wording.

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?

readOnlyHint=true already covers the safety profile, and the description reinforces scope by naming the topical areas returned (fees, buyer protection, earning model). An agent can predict this is a non-mutating informational read with no required inputs. It doesn't describe the response shape, but with no output schema a brief hint on format would be the only missing detail.

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

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

Two sentences, no filler: the content inventory comes first, the routing cue last. Nothing repeated from the title or annotations.

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 zero-parameter, no-output-schema info tool, the description is nearly sufficient — it says what topics come back and when to call it. The only gap is no hint about the return format or length, minor for an 'about' 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?

The schema takes zero properties, which is the correct baseline of 4 — there are no parameters whose meaning could be lost. The description correctly implies no input is needed.

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 enumerates the concrete subject matter (what the marketplace is, earning mechanics, fees, buyer protection, getting started), which tells an agent exactly what content this tool returns. It's a static documentation tool, not a verb+resource action, so an exact action verb isn't applicable. It implicitly distinguishes itself from action siblings by covering orientation rather than listings/orders/account.

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?

"Call this first if unsure" gives an explicit routing rule that no sibling offers, effectively declaring this the entry point when tool choice is ambiguous. It falls short of 5 because it doesn't name a specific alternative or condition (e.g., 'use search_listings for catalog queries').

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 readOnlyHint annotation already establishes that this is a safe read operation, lowering the disclosure burden. The description adds useful context about what account data is included, but it does not discuss authentication requirements, pagination, or response structure beyond the field list.

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 compact sentence with no wasted words. It could be slightly stronger if front-loaded with an explicit action verb such as 'Returns' or 'Retrieves' rather than starting as a noun phrase.

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 simple read-only account overview with one optional parameter and no output schema, the description covers the key returned fields and is largely complete. The main remaining gap is the absence of usage guidance relative to sibling tools.

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

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

Schema description coverage is 100%, and the single optional api_key parameter is fully documented in the schema. The description adds no additional meaning about that parameter, so the baseline score 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?

The description names the resource and enumerates the account data returned: profile, plan, payout wallet, and all listings with status. This makes the tool's purpose clear, though the noun-phrase phrasing lacks an explicit verb and does not explicitly differentiate it from siblings like get_balance or get_stats.

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 provides no when-to-use guidance, no exclusions, and no mention of alternatives such as get_balance or get_listing. An agent must infer from 'Your agent profile' that this is the account overview tool.

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, the description carries the full burden and delivers the two operationally critical facts: the call returns an api_key that is shown only once and must be stored, and subsequent calls must present it as an Authorization Bearer header. That is genuinely valuable context an agent could not get from structured fields. It stops short of covering edge cases such as name collisions or whether registration is idempotent.

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?

A single front-loaded sentence for the action, followed by the return-and-auth contract. No wasted words, and the most consequential detail (the one-time key) is placed immediately after the purpose.

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 two-parameter, no-output-schema tool, the description compensates for the missing output schema by explaining the return value (api_key) and how to use it. Only failure modes and any account-state implications are absent, which is a minor gap given the tool's simplicity.

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

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

Schema coverage is 100%, so both parameters (name with 2–60 chars, about with 10–500 chars) are already fully documented in the schema. The description adds no additional meaning about the parameters, so the baseline 3 applies.

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

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

States a specific verb and resource: "Create an AI agent seller account." This is unmistakably distinct from every sibling (listing, order, balance, and feedback tools), so an agent can select it without opening the 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?

Usage is only implied through "on later calls," which suggests this is the onboarding step preceding authenticated operations. It never explicitly says when to call this versus alternatives or what prerequisites exist, so the agent must infer the sequencing.

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 readOnlyHint annotation already establishes this as a safe read operation. The description adds useful behavioral context by saying it searches live listings and returns titles, prices, links, and whether items can be bought on-site. It still omits pagination behavior, but the annotation lowers the burden and the return-content summary adds real value.

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

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

The description is two efficient sentences. It front-loads the action and scope, then summarizes the return value without filler. Every sentence earns its place.

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

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

For a simple three-parameter search tool with no output schema, the description covers purpose, input filtering, and return contents well. It is not fully complete because page/pagination semantics and category-slug discovery are not explained, but those are minor gaps for a low-complexity search operation.

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 67%, with query and category already documented in the schema. The description reinforces that keyword and/or category filtering is supported, but it adds no detail for the page parameter. This is the baseline adequate level when the schema carries most parameter semantics.

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

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

The description states a specific verb and resource: search live listings on iamai.markets by keyword and/or category. It also summarizes return fields, so the agent knows this is a discovery/search operation. It does not explicitly differentiate itself from siblings like get_listing or list_categories, which keeps it short of a 5.

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

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

Usage is implied by 'by keyword and/or category,' which signals discovery-style lookup. However, it does not explicitly say when to use this instead of get_listing for a known listing or list_categories to discover category slugs. The guidance is adequate but leaves alternatives 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, the description carries the behavioral burden and does disclose the key traits: the team reads every message, and an API key produces a reply via get_notifications. It stops short of covering anonymity guarantees, moderation, or rate limits, but the core follow-up behavior is communicated.

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

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

Two tight sentences, front-loaded with purpose and followed by the follow-up mechanism. No filler.

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

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

For a simple three-parameter feedback tool with rich schema descriptions and no output schema, the description covers purpose, audience, and what happens after submission. Minor gaps like whether feedback is anonymous are acceptable.

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%, so the baseline is 3. The description adds real value by explaining the outcome of supplying api_key — a reply arrives in get_notifications — which gives the parameter behavioral meaning beyond its schema text.

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 — telling the iamai.markets team how to improve the marketplace or reporting a bug. That clearly separates it from transactional siblings such as create_listing or get_notifications.

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 first sentence gives the two intended use cases (improvement suggestion and bug report). It does not state exclusions or contrast explicitly with other tools, but the context is clear enough to choose it correctly.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the payout destination and prerequisite, but omits key mutation behavior such as whether it overwrites an existing wallet, auth requirements beyond the api_key parameter, validation rules, or irreversibility.

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

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

The description is two short fragments with no wasted words, and the purpose is front-loaded. It is slightly too terse to be a fully structured description, but it is efficiently sized for this simple 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 3-parameter mutation tool with no annotations and no output schema, the description covers purpose and prerequisite well enough to call it. However, it leaves important behavioral context unstated, such as overwrite semantics and authentication behavior, so it is adequate but not complete.

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

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

Schema coverage is 100%, so coin, wallet, and api_key are fully documented by the schema itself. The description adds no parameter-level meaning beyond the schema, which matches the baseline 3 for high-coverage schemas.

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 the resource and purpose: it is where earnings are sent, specifically crypto. It is clear enough to distinguish from siblings like buy_listing or get_balance, though it does not explicitly name the action or an alternative tool.

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 usage context: 'Needed before selling on-site.' That tells the agent when this tool becomes relevant, but it does not cover when-not-to-use it, whether it can be updated later, or how to check an existing wallet.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses partial-update semantics and ownership scope ('your listings'), but omits mutation-relevant behavior: required permissions, payout/delivery prerequisites, whether changes are reversible, and how validation failures are handled.

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?

A single front-loaded sentence with a useful parenthetical and zero wasted words. The partial-update constraint is surfaced immediately.

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 13-parameter mutation tool with no annotations and no output schema, the description is thin. The rich schema compensates for field-level rules, but the description should say more about ownership, permissions, and side effects of changing a live listing.

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 13 parameters in detail. The description adds only the partial-update rule and no per-parameter meaning, making the baseline 3 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 ('Change fields') and resource ('one of your listings'), which is enough to distinguish it from create_listing and delete_listing. It does not explicitly name siblings, so it falls short of a 5.

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

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

The parenthetical 'send only what changes' implies partial-update usage, but there is no explicit guidance on when to use this versus create_listing or delete_listing, nor any stated prerequisites or exclusions.

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