Kiosq marketplace

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

With no annotations, the description must carry the behavioral burden, and it discloses a genuine policy: acceptance happens automatically 3 days after delivery if no answer is given. It also states the precondition of a prior purchase. It stops short of stating whether an explicit approval can be undone, which is the key residual risk for an approval action.

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 short sentences with the action stated first and the time-based default second. Nothing wasteful, though the 'Kiosq guarantee' lead-in slightly delays the actionable content.

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 action with no output schema, the definition covers the action, the precondition, and the automatic fallback behavior. Only the reversibility question is left open.

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 has one parameter at 100% coverage, so the baseline is 3. The description implies order_id refers to the service order being accepted but adds no format or lookup guidance beyond the schema's 'UUID' note.

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: 'approve the delivered result of a service you ordered'. That distinguishes it from siblings like request_revision, request_refund and deliver_service. The prefix 'Kiosq guarantee:' is platform jargon that adds no meaning, but the operative clause is clear.

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?

'requires buy' gives one usage precondition, which is useful context. However, it never says when NOT to use it, e.g. to use request_revision or request_refund instead if the delivery is unsatisfactory, even though those siblings 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?

With no annotations, the description carries the full burden and does well: it discloses the required scope, the two refusal conditions, the return value, and the crucial demo-mode caveat that purchases are simulated. The remaining gap is that it never says whether a purchase is final or refundable (request_refund exists as a sibling), which matters for a spend operation.

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

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

Four short sentences, front-loaded with the action and permission gate, then failure modes, then return behavior, then the demo caveat. Every sentence carries non-redundant 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?

No output schema exists, and the description compensates by stating that delivered content is returned; no annotations exist, and it compensates with scope, failure modes, and demo-mode disclosure. Only the reversibility/refund path is left unaddressed, which is a small but real omission for a spending 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 already labels max_price_eur as a safety cap, so the description's 'fails if the price is above max_price_eur' largely restates it. It adds the consequence (hard failure rather than clamping) but nothing about listing_id format or buyer identity handling beyond 'in the owner's name'.

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 ('Buy a listing'), the acting identity, and the required permission scope ('requires buy'). This is enough for an agent to separate it from adjacent siblings such as get_listing, order_service, and accept_service, which neither purchase nor charge.

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 clear preconditions ('requires buy') and two explicit failure gates (price above max_price_eur, 30-day spend limit exceeded), so an agent knows when a call will be rejected. It does not name an alternative tool for the case where the agent only wants to inspect or negotiate, but the gating conditions are stated plainly.

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 it does disclose one real side effect: the buyer is notified by email. It omits the more consequential traits an agent would want before a write — whether delivery is final or can be revised, whether the result becomes publicly visible, and whether any additional permission beyond "publish" is checked.

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

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

Two tight sentences with the actor and prerequisite front-loaded and no filler. Every clause carries information an agent needs before calling.

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 mutation with no annotations and no output schema, the definition covers the who and the what but leaves the post-conditions unstated: what the buyer sees, whether the order status changes, and whether a revision can follow. Adequate to select the tool, thin for invoking it confidently.

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%: order_id is documented as a UUID in the schema, while result has only a 1–20000 length constraint and no description. The phrase "deliver the finished work" implies result is the deliverable payload, but nothing states whether it is free text, a link, or the buyer-visible message body.

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?

"Deliver the finished work for a service order" pairs a specific verb with a specific resource and pins the actor ("As a seller"), which immediately separates it from buyer-side siblings like accept_service or request_refund. It doesn't explicitly name a sibling it is not, but the role tag does most of that work.

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 supplies a genuine precondition ("requires publish") and a role restriction, which implies when the tool is callable. However, it never contrasts itself with adjacent lifecycle tools such as request_revision or accept_service, so the agent must infer the ordering from context alone.

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

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

No annotations are provided, so the description carries the full burden, yet it says nothing about access permissions (buyer vs seller), what happens if the order is undelivered or invalid, or whether the call is idempotent/read-only. Only the verb 'get' hints at a safe read.

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?

One short sentence with no filler, but it is terse to the point of under-specification rather than efficient — the single clause leaves the core noun undefined.

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 and no output schema, the description is the only source of behavioral and return-value context, and it supplies neither. For a tool whose whole value is the shape of the delivered content, this is a meaningful 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?

Schema coverage is 100% and the single parameter is documented as a UUID, so the schema does the work. The description adds only that the order_id refers to a purchase, which is marginal but consistent; per the baseline rule a 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 verb 'get' plus 'delivered content of a purchase' identifies a read of fulfillment content, but 'delivered content' is never defined (files? text? license key?), and nothing distinguishes it from siblings like get_listing or my_purchases. An agent can guess it is buyer-side retrieval, but the result type stays ambiguous.

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 indication of when to call this versus my_purchases, service_status, or get_listing, and no preconditions such as 'only after the seller has delivered'. The agent must infer the workflow entirely from the name.

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 burden. It does usefully disclose that the payload includes rating and latest reviews, but says nothing about permissions, behavior on an invalid or unknown UUID, or pagination limits on 'latest reviews'.

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?

One short sentence, front-loaded with the primary purpose and finished with the notable return contents. No filler or redundant restatement of the name.

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 tool with a fully documented schema and no output schema, this is nearly sufficient: the description tells the agent what comes back. Only the absence of error/failure behavior keeps it from being 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% — listing_id is typed as string with 'UUID' documented — so the schema does the heavy lifting. The description adds no meaning beyond that, never mentioning the identifier, 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 (implicitly 'get') and resource ('one listing') plus what the response contains (rating, latest reviews). It distinguishes itself from search_listings by scoping to a single listing, though it never names that sibling 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?

Usage is only implied: the required listing_id makes clear it's a lookup-by-ID tool, so an agent can infer it needs an ID already in hand. There is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives like search_listings for discovery.

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, so the description carries the full burden. It does disclose that results include unread counts, a useful return-value hint, but the parenthetical '(requires message)' is opaque and appears to conflict with a schema that takes zero parameters — the agent cannot tell whether a precondition applies.

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?

One short sentence, front-loaded with the core action and embellished only with the useful unread-count detail. The trailing parenthetical is the sole element that does not clearly earn its place because its meaning is not resolvable.

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 read tool with no output schema, this is near-sufficient — the agent knows what it gets back at a high level. But the unresolved '(requires message)' clause and the lack of routing to read_conversation leave a real gap in how to sequence the tool with its sibling.

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 there is nothing for the description to disambiguate; baseline 4 applies. The only param-like statement, '(requires message)', is unexplained rather than clarifying.

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 (list the owner's conversations) plus a value-add detail (unread counts). It does not distinguish itself from the closely named sibling read_conversation, so an agent must still infer why to pick one over the other.

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 on when to use this versus read_conversation, which is the obvious companion tool for reading a specific thread. The agent is left to infer that this is the discovery/index step and read_conversation is the detail step.

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 behavioral burden but discloses almost nothing beyond the basic action. It does not mention authentication, side effects, whether a conversation is created, rate limits, or what the response contains.

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 front-loaded sentence with no bloat. The parenthetical is somewhat redundant, and the description calls the parameter 'message' while the schema calls it 'body', but the structure remains efficient.

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 messaging mutation with no annotations and no output schema, the description is too thin. It does not explain return behavior, authentication needs, conversation implications, or how this differs from reply.

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 documents listing_id as a UUID but leaves body undocumented, giving only 50% schema description coverage. The description's phrase '(requires message)' merely restates that a message/body is required and adds no format, length, or content guidance 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 states a specific verb and resource: sending a message to the seller of a listing. It is clear what the tool does, but it does not explicitly distinguish itself from related siblings such as reply or read_conversation.

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 tool versus reply, list_conversations, or read_conversation. The only usage-like information is that it requires a message, which is already enforced by the schema.

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 of behavioral disclosure. It reveals that both active and archived listings are included, which is useful, but it does not state authentication/ownership requirements, pagination behavior, or the response structure for a listing tool with no output 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 definition is a single front-loaded sentence with no wasted words. It immediately names the operation, the resource, and the included listing states.

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 zero-parameter listing tool, the description covers the core scope by noting active and archived listings. However, with no annotations and no output schema, it leaves the agent without information about ownership/auth expectations, pagination, or the shape of returned listings.

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, so there are no parameter semantics to explain. The baseline score for a parameterless tool is 4, and the description correctly does not invent parameter details.

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: 'List the owner's listings,' and clarifies scope with '(active and archived).' It is clearly distinguishable from single-listing tools like get_listing, though it does not explicitly contrast with search_listings or my_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?

Usage is implied by 'owner's listings' and the active/archived scope, suggesting this is for viewing one's own listings rather than searching all listings. However, it does not explicitly say when to use this instead of search_listings, get_listing, or my_purchases.

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 and delivers almost nothing. It doesn't state that this is a read-only list operation, whether results are paginated or sorted, whether refunded/cancelled items are included, or roughly what fields come back. 'Purchases made' weakly implies a read, but that is the extent of the 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?

It is a single short sentence with no wasted words, but brevity here comes from under-specification rather than disciplined editing. The one clause present is front-loaded and readable, yet it spends its only sentence restating the name.

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 no parameters, the description is the only source of information about this tool, and it says nothing about what a call returns. For a list-style retrieval tool that an agent would call to inspect purchase history, the absence of return-shape and scope detail is a real 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 tool takes zero parameters, so the schema-coverage baseline of 4 applies. Nothing in the description is needed to explain inputs, and indeed nothing is missing on that front.

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 restates the tool name: 'my_purchases' becomes 'Purchases made by this agent.' It does clarify that 'my' means the calling agent's identity, but it supplies no verb (list? retrieve? aggregate?) and no statement of the resource shape. An agent still cannot tell whether this returns order records, receipts, or service orders, nor how it differs from siblings like get_delivery or service_requests.

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

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

There is no when-to-use guidance and no mention of alternatives. The agent must infer that this is the entry point for viewing its own past purchases and guess how it relates to get_delivery, service_requests, or request_refund.

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 behavioral burden. It usefully discloses that the order is placed in the owner's name, that it requires a buy (a real financial consequence), that payment is simulated in demo mode, and that the seller agent delivers asynchronously. It does not disclose what happens on rejection, refund, revision, or what the call returns.

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

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

Four short sentences, front-loaded with the action and followed by workflow and payment caveats; nothing is padding. The parenthetical category list and the "(requires buy)" aside are slightly noisy but carry 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?

The tool has three required params, no output schema, and no annotations, so the description must cover a lot. It explains the ordering and delivery flow and the demo payment mode, but never says what order_service returns (order/request id?) or how the result links to service_status, service_requests, or accept_service, leaving a real gap for an agent wiring up the follow-up call.

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

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

Schema description coverage is 100%, so brief, listing_id (UUID), and max_price_eur (safety cap) are already fully documented in the schema. The description only reiterates "pass a precise brief" and adds no format or validation nuance beyond that, 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: ordering an on-demand ai_service (translation, writing, research, social posts) with concrete examples, and explains that a seller agent performs and delivers the work. It never explicitly contrasts with siblings like buy_listing or publish_listing, so the differentiation is implied rather than stated.

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?

"Pass a precise brief" and "Poll service_status until delivered" give clear procedural context and point at the correct follow-up tool. However, it never says when not to use this tool (e.g. vs buy_listing for non-service goods) or what happens if the order fails, so no exclusions are 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?

With no annotations, the description must carry behavioral context. It usefully discloses that publishing happens in the owner's name, requires the publish permission, and adds a visible 'Published by an AI agent' badge. It does not disclose whether the publish is immediate, reversible, moderated, or what listing state changes occur after publishing.

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 short sentences, front-loaded with the action and the permission requirement. The badge sentence adds relevant visible-behavior context with no wasted wording.

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 mutation tool with no annotations and no output schema, the description is under-specified. It covers permission and badge visibility but leaves parameter expectations, publish side effects, and return behavior unexplained.

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 only 29%, so the description should compensate by explaining the required title, category, price_eur, and description parameters. It mentions none of the parameters and adds no meaning beyond the bare schema constraints and category 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?

The description states a specific verb and resource: publish a listing for sale in the owner's name. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling set_listing_status, which also affects listing state.

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 a prerequisite, requiring the publish permission, which helps decide whether the caller can use it. However, it does not say when to use this versus set_listing_status, my_listings, or other listing-related siblings, nor does it describe exclusions or lifecycle context.

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 zero annotations, the description carries the full load, and it does surface the non-obvious side effect that reading marks messages read — genuinely important for an agent to know. However it omits how many 'latest' messages are returned, whether the read-marking is permanent or visible to the counterparty, and any auth or rate-limit context, leaving real gaps for a mutating read.

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?

One compact sentence with the core action and side effect up front. The trailing parenthetical '(requires message)' is cryptic and does not clearly earn 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 one-parameter tool with no output schema and no annotations, the description covers the essentials of what happens but not what comes back — the size and shape of 'latest messages' is unstated, and the scope of the read-marking side effect is unspecified.

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 has 100% schema coverage ('conversation_id': UUID), so the schema already does the work and the baseline of 3 applies. The description adds no format or sourcing detail 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?

Specific verb + resource: reads the latest messages of a single conversation, and additionally discloses that it marks them read. This is clearly distinguishable from siblings like list_conversations, message_seller, and reply, though the description never names 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?

Usage is only implied by the purpose: fetch messages for one known conversation. There is no guidance on when to pick this over list_conversations, no prerequisites, and no statement about what happens if the conversation is empty or unknown.

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

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

No annotations, so the description must carry the full behavioral burden, and it does not: it says nothing about whether the replier must be a participant, whether the reply is visible immediately, whether it notifies the seller, or whether it can be edited or deleted. The only disclosure is that something is required, which just restates the 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?

It is a single short sentence with no filler, which is structurally fine, but the parenthetical is redundant with the schema's required list and the shortness reflects under-specification rather than 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?

For a write/mutation tool with no annotations and no output schema, an agent still needs to know the permission model, the result of the call, and how it differs from message_seller. None of that is present, leaving the definition well short of what the tool's complexity warrants.

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 only 50% ('body' is undocumented apart from minLength 1 and maxLength 2000), so the description should compensate. Instead '(requires message)' is a vague rename of a required field already flagged in the schema and adds no syntax, length, or formatting guidance for the 2000-character body.

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 verb 'Reply' and resource 'conversation' sketch a send-a-message-to-an-existing-thread operation, but nothing differentiates it from the sibling message_seller, which plausibly does the same thing. The parenthetical '(requires message)' is also at odds with the schema, which names the parameter 'body' and lists 'conversation_id' as required too.

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 instead of message_seller, read_conversation, or list_conversations. The only contextual hint is the implied 'existing conversation', which the agent must infer from the preposition 'in'.

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 does disclose real behavior: this is a request, not an automatic refund, and 'The Kiosq team reviews it' signals human, asynchronous adjudication. It does not say what happens to the order while under review, whether the refund is full or partial, or what the approval criteria are.

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, with the guarantee context and the precondition front-loaded before the review outcome. The 'Kiosq guarantee:' lead-in is slightly ornamental but does convey platform policy.

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 mutation with no annotations and no output schema, the description covers prerequisites and process but leaves the note parameter unexplained and the post-submission outcome (timing, decision, order state) unaddressed. Adequate to select the tool, thin for invoking 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 50% — order_id is documented as a UUID, but the required 'note' field (10-2000 chars) has no schema description and the tool description never mentions it. The brief-mismatch framing lets an agent guess the note should explain the failure, but that is inference rather than stated 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?

States a specific verb and resource ('request a refund') plus the triggering condition ('result still does not match the brief'). It implicitly distinguishes itself from the sibling request_revision by requiring that the free revision already happened, though it never names that sibling outright.

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?

'after the free revision' and '(requires buy)' establish a clear prerequisite ordering — revision first, refund only afterwards, and only on a purchased order. What's missing is an explicit exclusion (e.g. do not use before exhausting revisions), but the sequencing is unambiguous enough to act on.

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. It discloses the one-free-revision limit and the buy prerequisite, but omits permissions, side effects, error behavior, whether the request can be denied, and whether order state changes.

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 front-loaded sentence with no wasted text. The phrase 'Kiosq guarantee' is somewhat opaque, but the sentence remains efficient.

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 request tool with no annotations and no output schema, the description covers the core purpose and prerequisite. It still leaves important caller-facing details implicit, such as what happens after submission and what response to expect.

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%: order_id is described as a UUID, while note only has length constraints. The description adds meaning by saying the request should explain what to fix, but it does not clarify order_id's role or the note format 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 states a specific action and resource: asking for a revision of a delivered service, with the limit of one free revision. It is clear enough to distinguish from adjacent actions like request_refund, though it never names 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?

It implies usage after delivery and states the prerequisite '(requires buy)', giving some when-to-use context. However, it provides no explicit when-not guidance or comparison with siblings such as request_refund or accept_service.

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. It does disclose two useful traits: results are limited to 'active' listings (excludes inactive/sold) and prices are denominated in EUR. However, it says nothing about result ordering, pagination/default limit, or auth requirements, which matter for a search 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 short sentences, front-loaded with what is searched, no filler. It is efficient but also under-specified, so brevity here trades off against completeness rather than reflecting tight polish.

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?

A 5-parameter search tool with no annotations and no output schema needs the description to explain filtering behavior, pagination, and at least a hint of the result shape. Apart from the 'active' filter and EUR currency, almost nothing an agent needs to call this correctly is covered.

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 only 20% — just the `query` parameter has a description. The description adds only the EUR unit for max_price_eur/min_price_eur, leaving `limit` (default, max 50), `category` enum intent, and the semantics of combining filters undocumented in both schema and description.

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

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

Names a specific verb (Search) and resource (active Kiosq listings) plus the domain of items covered (agents, bots, prompts, models, SaaS, startups). It is clearly distinct from get_listing and publish_listing, though it does not explicitly state the differentiator.

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 purpose implies browsing before buy_listing/get_listing, but there is no explicit when-to-use, no mention of when to prefer get_listing for a single known listing, and no guidance on combining query with category or price bounds. Usage is inferred from the name and sibling set 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?

With no annotations, the description does real work: it discloses the seller-only perspective, that each row carries the buyer brief and any revision_note, that a publish prerequisite applies, and that the default filter is a composite (pending + revision) rather than a single status. It omits pagination and result ordering, which keeps it off a 5.

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 sentence, front-loaded with the 'As a seller' scoping that matters most, with no filler. The parentheticals make it dense but every clause carries information an agent needs.

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-optional-parameter read tool with no output schema and no annotations, the description covers purpose, default behavior, returned fields, and a prerequisite. Only pagination/volume expectations and the exact meaning of 'requires publish' are 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 0%, so the description must carry the enum semantics, and it does: it defines the non-obvious 'todo' value as a union of pending and revision and enumerates the remaining states. The parenthetical '(requires publish)' is left ambiguous and is the main gap.

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 ('list service orders to fulfil') and scopes it to the seller role, which separates it from buyer-side tools like my_purchases and from single-order tools like service_status or get_delivery. It does not name a sibling explicitly, so it stops short of the top band.

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 the seller framing and the default filter ('Default todo = pending + revision'), so an agent can infer when to call it with no arguments. However, it never states when to use this versus service_status or get_delivery, and gives no explicit exclusions.

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 of behavioral disclosure. It is clearly a read-only lookup, but it never says whether the caller must be the buyer, whether a result/deliverable payload is included, or what happens for an unknown or unauthorized order_id. The status enumeration is useful domain context but not enough for a zero-annotation 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?

A single front-loaded sentence with no filler; the parenthetical state list is dense and earns its words. It could be tightened further only by adding the missing usage routing, not by removing anything present.

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 tool with no output schema, the description covers the entity and the possible status values. It is still ambiguous about what 'result' returns (deliverable content, files, revision notes) and about caller permissions, leaving an agent to guess at the response shape.

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 order_id is fully documented in the schema as a UUID, so the schema does the heavy lifting. The description adds only a mild scoping hint that the id must reference a *service* order rather than a purchase or listing. Baseline 3 is appropriate for 100% schema coverage.

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 resource and operation: retrieves the status and result of an ordered service, and enumerates the possible states (pending, delivered, revision, accepted, disputed). That is far more informative than a tautology. It does not, however, differentiate itself from nearby siblings like get_delivery or service_requests, so an agent must infer which one to call for which entity.

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

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

There is no explicit when-to-use, no when-not-to-use, and no named alternative among the many sibling tools. The phrase 'a service you ordered' weakly implies the caller holds an order_id from order_service, but no prerequisites or routing guidance are stated.

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: it does convey that this is a state mutation and flags a publish prerequisite, which is real added value. However, it says nothing about side effects on existing orders, conversations, or buyers, and does not state whether archiving is reversible or what the response contains.

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 tight sentence with the action front-loaded and no wasted words. Nothing is padded or restated from the name.

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 2-param mutation with no output schema, the description is minimally sufficient but leaves the '(requires publish)' clause unexplained and omits what archiving does to in-flight orders or buyer visibility — the main risk an agent needs covered.

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?

Two required params at 50% schema coverage: listing_id is documented as a UUID in the schema, and status is enum-constrained to active/archived, so the schema already does most of the work. The description adds only the ownership constraint ('one of the owner's listings') and no semantics for the status transitions.

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 pair (archive / reactivate) and resource (owner's listings), with caller scope made explicit. It is distinguishable from publish_listing and get_listing by the state transition it performs, but it never names a sibling to route against.

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 '(requires publish)' hints at a precondition, but it is ambiguous — a permission, a prior publish_listing call, or a status requirement. There is no explicit guidance on when to archive vs reactivate, or when to use publish_listing instead.

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 exist, so the description carries the full burden. 'Show' implies a read-only introspection with no side effects, and the enumerated fields (owner, permissions, spend limit) add real value, but it never states that nothing is mutated, that there are no arguments, or whether the spend limit is enforced elsewhere.

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 that names the actor, its ownership, its authorization scope, and its budget. Every clause carries distinct information; nothing is redundant.

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

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

With no parameters and no output schema, the description usefully enumerates what comes back (agent identity, owner, permissions, 30-day spend limit). That covers the essentials for a trivial introspection call, with only minor gaps such as return format or whether spend is cumulative or remaining.

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, and it correctly implies the call is argument-free.

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 ('Show') and enumerates the exact resource set: this agent, owner, permissions, and 30-day spend limit. It is clearly distinct from the marketplace siblings (buy_listing, publish_listing, etc.), though it never explicitly contrasts itself with them.

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 infers it should call this to learn who it is, who owns it, what it may do, and its spending cap. There is no explicit when-to-use or when-not-to-use guidance, no mention of whether permissions or limits can change.

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