Partle

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

The description adds substantial behavioral detail beyond annotations: required OAuth scope, API key override behavior, non-idempotence, and specific return/error formats. It openly states 'each call creates a new row' and explains the deduplication semantics of external_id. These are critical traits not inferred from annotations alone.

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?

Despite its length, the description is tightly structured with an intro, Args section, and Returns section. Every sentence contributes necessary semantics—no filler. The length is appropriate for the 15-parameter complexity, and key information (auth, non-idempotence) is front-loaded.

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

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

The description is complete for the tool's complexity: all parameters are explained, auth and error behavior are disclosed, and the return value is described despite no output schema. It also provides enough context to differentiate from siblings like mark_for_sale and create_buy_request by covering the full lifecycle state machine.

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 no descriptions for its 15 parameters, and the description compensates thoroughly. It explains mutual exclusivity (name/product_id), status enum values with defaults, fractional quantity, external_link one-link rule, external_id dedup behavior, and even notes formatting. This goes well beyond the schema's bare type definitions.

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

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

The description opens with 'Add an item to the caller's personal inventory,' which is a specific verb+resource+scope statement. It clearly distinguishes from sibling tools like update_inventory_item and create_product by positioning itself as the creation tool for personal inventory. The lifecycle status mapping further clarifies its role.

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 clear usage context: it explains how to set status based on user intent ('I bought' → owned, etc.) and explicitly notes the tool is not idempotent, warning against duplicate creation. However, it does not explicitly name alternative tools for updates or deletes, so it falls short of 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?

Beyond the annotations, the description discloses that the call is not idempotent, requires authentication with a specific OAuth scope, and explains how api_key overrides narrow tokens. It also states that invalid tokens still fail and that each call creates a new public post—useful behavioral context.

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

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

The description is front-loaded with the core purpose and usage trigger, followed by authentication constraints, detailed argument semantics, and return behavior. Each sentence adds value; the structured Args block makes the long definition scannable.

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 no output schema, the description still states the return value shape ('newly-created buy request, or {error: ...}'), covers authentication and override behavior, and explains the public feed context. An agent has enough information to select and invoke the tool correctly without additional lookup.

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 0%, yet the description documents all 9 parameters with meaningful guidance: name is called required, quantity defaults to 1, max_price is a per-unit ceiling, and contact explains the public visibility and supplier-response implications. This fully compensates for the bare 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: 'Post a public buy request — an ad asking suppliers to reach out.' It clearly distinguishes the tool from inventory management and identifies the public demand feed at /wanted, so an agent can tell it apart from siblings like add_inventory_item and search_wanted.

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?

'Use when the user wants others to know they're looking to buy something' gives a clear trigger condition. It also explicitly separates buy requests from personal inventory, preventing cross-tool confusion, though it does not name a specific alternative tool to use 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?

The description goes far beyond the annotations. It explains the image upload mechanism (separate upload_url, PUT request, not through conversation), duplicate prevention (409 with existing.id and fresh upload_url), idempotency (idempotency_key behavior), listing_type semantics (in_stock vs tentative vs create_buy_request), and api_key override behavior. It also describes the response format and error handling. Annotations already provide idempotentHint=true and readOnlyHint=false, and the description fully aligns and adds rich context.

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

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

The description is long but well-structured with section headers and bold text. It is front-loaded with the purpose. Every sentence adds value, and for a tool with 9 parameters plus complex behaviors, the length is justified. It could be slightly more concise, but it 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?

Given the tool's complexity (9 parameters, no output schema, complex auth, image upload, dedup, idempotency), the description covers all aspects. It explains the return value, error handling, provides a code example for image upload, and mentions alternative tools. It is fully self-contained and 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 description coverage is 0%, so the description must fully compensate, and it does. Every parameter is explained with constraints, defaults, and usage notes. For example, price: 'Price in whole currency units, not cents (e.g. 15.99 means €15.99). Max 100000. Omit for ask the seller.' listing_type: detailed explanation of in_stock vs tentative. idempotency_key: purpose and uniqueness. api_key: override behavior. This is exemplary.

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 starts with a clear verb-resource-platform statement: 'Create a new product listing on Partle.' It explicitly distinguishes from sibling tools: 'For edits to an existing product, use update_product instead' and 'If the user is looking to buy something nobody sells, use create_buy_request instead.' This provides excellent purpose clarity.

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 explicitly states when to use: 'Use when the user wants to add an item for sale.' It gives clear alternatives for edits (update_product), demand-side (create_buy_request), and image upload (upload_product_image). It also includes authentication guidance (OAuth vs api_key) and scope requirements. No gaps.

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

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

Beyond the annotations (destructiveHint, idempotentHint), the description details auth requirements, OAuth scope, hard-delete semantics, ownership verification, API key override behavior, and the exact return/error format. This is rich behavioral disclosure.

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

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

The description is efficiently structured with a clear opening sentence, followed by auth notes, args, and returns sections. Every sentence adds value; there is no redundancy or 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 delete tool with no output schema, it comprehensively covers prerequisites (auth, scope, ownership), behavior (permanent, hard delete), and outcomes (success and error shapes). This is more than sufficient for an agent to use it correctly.

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

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

The schema only provides types and defaults, but the description fully explains item_id as the row ID and api_key with its format, generation location, and override semantics. Since schema description coverage is 0%, the description carries the entire burden and does so thoroughly.

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

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

The description opens with 'Permanently delete an inventory row,' which is a specific verb+resource statement. It also clarifies 'Hard delete — no soft-delete,' distinguishing it from any potential soft-delete alternatives among siblings like update_inventory_item.

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 clearly states authentication, required OAuth scope, and ownership condition ('Caller must own the item (404 otherwise)'). It also explains when to use the optional api_key (when no OAuth token or insufficient scope). However, it does not explicitly compare with alternative tools like update_inventory_item for non-destructive changes, so a perfect 5 is not given.

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?

Goes far beyond the annotations, detailing auth fallbacks (OAuth scope and api_key override), idempotency behavior (returns error on missing product), and the irreversibility with no trash bin. These traits are not present in the annotations alone, adding significant 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 somewhat long but well-structured with clear sections (auth, usage, args, returns). Every sentence adds value; the length is justified for a destructive operation with complex auth behavior.

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 destructive nature, no output schema, and the need to convey error/edge cases, the description covers success/error returns, ownership, idempotency, and auth. It is complete for an AI agent to decide and invoke the tool 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?

Although schema description coverage is 0%, the description thoroughly explains both parameters: product_id with a source pointer to get_my_products, and api_key with detailed fallback/override rules. This fully compensates for the schema's lack of descriptions.

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

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

The description uses the specific verb 'delete' with the resource 'product listing' and clarifies it includes 'all its images.' It clearly distinguishes from sibling tools like delete_product_image or delete_inventory_item by specifying the permanent and destructive nature.

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 provides clear usage guidance: 'Use only when the user explicitly asks to remove a listing they own' and states an important exclusion (no soft-delete/trash bin). It also mentions ownership prerequisites, though it does not explicitly name alternative tools for partial deletion.

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

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

The description discloses significant behavioral details beyond annotations: destructive effect ('the image record and its file are removed'), idempotent nature, auth requirements (OAuth preferred, api_key fallback), and subtle auth override behavior (explicit key overrides narrowly-scoped OAuth token, but invalid token still fails). These traits aren't captured by the annotations alone and add valuable context for invocation.

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 well-structured with labeled sections (purpose, usage, args, returns). Every sentence provides necessary information—purpose, use cases, auth nuances, parameter semantics, and return format. It is appropriately sized for a destructive mutation tool and front-loads the key 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?

The description covers all essential context: authentication methods, idempotency, exact deletion scope, a return example, and error conditions. Even without an output schema, the Returns section clarifies expected success and failure shapes. For a destructive mutating tool with three parameters and no output schema, this description is 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?

The input schema has zero description coverage, but the description's Args section thoroughly explains each parameter: product_id is the parent product, image_id is visible in get_product responses, and api_key is optional with detailed fallback logic. This fully compensates for missing schema documentation and adds meaning beyond raw parameter types.

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

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

The description opens with a specific verb and resource: 'Remove a specific image from a product.' It clearly states the tool's destructive nature and idempotency. It also differentiates from the sibling tool delete_product by noting 'only the image record and its file are removed' and explicitly referencing delete_product for product removal.

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

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

Provides explicit use cases: 'Use when an image was uploaded by mistake or the merchant updated their listing.' It also states what the tool does NOT do ('The product itself is preserved') and names the alternative: 'To remove the product entirely use delete_product.' This directly addresses when to use this tool vs alternatives.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description discloses authentication requirements (OAuth scope `inventory:read` or api_key), details the api_key override behavior for insufficiently-scoped tokens, and specifies the return format including error responses. This is rich behavioral context not available in annotations.

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

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

The description is well-structured and front-loaded with a one-line purpose, followed by auth, usage examples, parameters, and return format. Every sentence provides necessary information—no filler. The use of an Args block and Returns block creates clear scannable sections despite being detailed.

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 complexity (7 optional parameters, no output schema, no enum constraints in the schema), the description provides a complete picture: auth scope, parameter semantics, default behavior, pagination limits, return structure, and error handling. It covers everything an agent needs to call this tool correctly and interpret the response.

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 input schema only lists parameter names, types, and defaults with no descriptions. The tool description compensates fully by explaining each parameter: status enum values (owned, wanted, for_sale, sold, discarded), substring search on `name` and `notes`, exact-match for project, pagination size and offset, and the nuanced api_key fallback logic. This adds substantial meaning.

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

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

The description opens with a specific verb+resource: 'List the caller's personal inventory items.' It further clarifies the purpose with example user queries ('what do I own?', 'what's on my wishlist?', etc.) and distinguishes this tool from sibling tools like get_my_products by focusing on inventory lifecycle statuses.

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 explicitly states when to use the tool ('Use this when the user asks...') and explains the default behavior of returning all statuses with optional filtering. However, it does not mention any alternatives or explicitly say when not to use this tool, so it lacks the full 5-level 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?

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses authentication details (OAuth scope preference, api_key fallback, behavior with insufficient scope, invalid key failure) and the return behavior including the error format on auth failure. This goes well beyond the structured annotations.

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

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

The description is well-structured with clear sections (auth, usage, args, returns) and front-loaded with the main purpose. It is slightly longer than strictly necessary, but every sentence adds value, so the length is justified.

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

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

The description covers purpose, usage context, authentication, parameters, and return shape. Given the tool's low complexity (2 parameters, no nested objects) and the presence of an output schema, this description is complete and self-sufficient.

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?

Even though the schema only lists `limit` and `api_key` without descriptions, the description adds crucial semantics: the limit range (1–200, default 50) and the full fallback/override behavior for `api_key`, including when to omit it and what happens with invalid/revoked tokens. This fully compensates for the 0% schema description 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?

The description opens with 'List products created by the authenticated user,' which is a specific verb+resource+scope statement. It also explicitly differentiates from the sibling `search_products` by noting that the sibling searches the public catalog without owner scoping, making the purpose unmistakable.

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 direct usage guidance: 'Use when the user asks "what have I listed?" or before bulk operations like updating prices across multiple of their products.' It also names the alternative (`search_products`) and explains the distinction, giving the agent clear decision criteria.

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

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

The description adds meaningful context beyond annotations: it explicitly states 'Read-only. No authentication,' and describes the return behavior including the canonical partle_url and error response for nonexistent IDs. This is consistent with readOnlyHint and destructiveHint.

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 well-structured with an opening summary, usage guidance, and explicit Args/Returns sections. Every sentence adds value, and the length is appropriate for the information conveyed.

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

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

Despite lacking an output schema, the description fully covers return values ('A single product object with all fields'), error cases, parameter sourcing, and usage context. It is complete for an agent to use 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?

The schema only defines product_id as an integer with no description. The description enriches it by explaining it comes from a search_products result or a Partle product page URL (/p/<id>-<slug>), which is essential for correct usage.

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

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

The description clearly states the tool gets the full record for a single product by numeric ID. It distinguishes itself from siblings like search_products, which returns only search summaries, and from other product-related tools by emphasizing the 'full record' scope.

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

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

It explicitly says when to use this tool ('Use after search_products returns a candidate... when you need fields not in the search summary') and when not to ('Don't loop get_product over many search results — re-search with tighter filters instead'). This provides clear context and an alternative action.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes beyond this by stating 'No authentication,' 'Cheap, but rarely changes,' and recommending caching. It also discloses that the result is aggregate-only. These details are not present in the annotations and significantly enhance transparency.

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 concise but information-dense. It front-loads the core purpose in the first sentence, then systematically covers usage, exclusions, behavior, and return format. Every sentence contributes meaning, with no redundancy or 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 tool with no parameters and no output schema, the description is fully complete. It explains purpose, usage context, behavioral traits (read-only, no auth, caching), and the exact return structure. This is more than sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema has zero parameters, so the baseline is 4 per rubric. The description adds value by specifying the exact shape of the return value, which is not in the schema. Although there are no parameters to explain, the description effectively communicates what the tool produces, which is sufficient for this dimension.

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

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

The description opens with a specific verb and resource: 'Get top-level Partle platform statistics.' It immediately clarifies scope with example questions and explicitly distinguishes itself from sibling tools by stating 'no per-product or per-store data; use search_products / search_stores for that.' This makes the tool's purpose unmistakable and differentiates it from alternatives.

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 explicit usage guidance: 'Use for size questions' and directly names alternative tools for per-product/per-store queries. It also adds operational context (read-only, no authentication, cheap, cacheable), which helps the agent decide when to invoke this tool versus siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds 'Read-only. No authentication,' which goes beyond annotations by specifying security requirements, and describes error behavior for non-existent IDs. It does not enumerate all return fields, but given no output schema, it could provide more detail; still, the added context is meaningful.

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 well-structured with a clear purpose, usage guidance, safety note, and argument/return sections. Every sentence contributes essential information without redundancy.

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

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

For a simple get-by-ID tool with one parameter and no output schema, the description covers purpose, usage context, parameter provenance, and error behavior. It is fully sufficient for safe and correct invocation.

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

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

The input schema only says 'store_id: integer' with no description. The description enriches this by noting it is 'Integer `id` from a `search_stores` result,' telling the agent exactly how to source the value. This compensates for the 0% 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?

The description opens with 'Get the full record for a single store by its numeric ID,' a specific verb+resource+scope statement. It also distinguishes itself from sibling tools by contrasting with search_stores (search summary vs full record) and search_products (store metadata vs product list).

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

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

Explicitly states 'Use after search_stores to retrieve fields not in the search summary' and 'For a list of products in that store, call search_products(store_id=…) instead,' providing clear when-to-use and when-not-to-use guidance with named alternatives.

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

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

Adds substantial behavioral detail beyond annotations: URL validity (~15 min), one-shot, signed with identity, no auth header on the PUT, the URL is the credential, and failures return error details. No contradiction with annotations (readOnlyHint false, idempotentHint true, destructiveHint false).

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

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

Although lengthy, every section earns its place: purpose, use cases, auth, code example, alternative, params, returns. The content is front-loaded with the core purpose and broken into readable sections. No wasted words.

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 no output schema, the description includes an explicit Returns section. It covers auth, behavioral constraints (expiry, one-shot PUT), usage flow, error conditions, and alternative tool paths. This is complete for an upload-URL minting 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 0%, but the description fully compensates through an Args section. product_id is explained with ownership requirements. api_key gets deep semantic detail: fallback, override behavior for narrow OAuth scopes, invalid-token failure, and when to omit.

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+resource+scope: 'Mint a one-shot signed upload URL for a product you own.' It distinguishes from sibling upload_product_image by explicitly redirecting public-URL use cases, and clarifies the 409-duplicate scenario. Purpose is unmistakable.

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

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

Provides explicit when-to-use context: local bytes, attaching to an existing product, duplicate-name 409 recovery, adding additional photos. Explicitly names the alternative upload_product_image for public URLs. Also explains auth requirements and when to omit/use api_key.

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

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

Beyond the annotations, the description discloses atomicity ('sets all three columns ... atomically'), auth override behavior via api_key, required scope, ownership requirement, and the return format including error case. This is rich behavioral context that the annotations alone do not provide.

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 well-organized with a summary, usage context, Args section, and Returns. Every sentence adds meaningful information without fluff. The structure makes it easy to scan and parse.

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 moderate complexity and the absence of an output schema, the description fully covers expected behavior, input semantics, auth requirements, and return value. It also distinguishes itself from update_inventory_item, making the contextual picture 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?

With 0% schema description coverage, the description compensates fully by explaining every parameter: item_id, asking_price ('Whole units, not cents'), asking_currency default, condition as free string, and api_key usage. This goes far beyond the raw schema field names.

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 exactly what the tool does: 'Move an inventory item to status=for_sale and set listing fields' and positions itself as a convenience wrapper over update_inventory_item. It matches a natural user request and is clearly distinct from siblings like mark_sold and update_inventory_item.

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

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

Explicitly names update_inventory_item as the underlying alternative and gives an example of when the wrapper is appropriate ('list my drill for sale at 30€'). Also specifies auth preconditions: OAuth scope required and caller must own the item.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses auth requirements, OAuth scope, ownership, API key fallback behavior including override and invalid-token failure. This is rich contextual behavior that annotations alone don't provide.

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 well-structured with sections for Args and Returns. Every sentence adds value: purpose, wrapper context, auth, parameters, return format. No wasted words.

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

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

For a tool with no output schema, the description clearly states the return value (updated row or error). It covers auth, ownership, parameter behavior, and error cases, making it fully self-sufficient.

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 has 0% description coverage, and the description fully compensates with an Args section explaining item_id and api_key semantics, including key override behavior and fallback logic. This adds significant meaning 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 uses a specific verb+resource+state: 'Mark an inventory item as sold (status=sold).' This clearly distinguishes it from siblings like mark_for_sale and update_inventory_item. The purpose is unambiguous.

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

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

Explicitly identifies itself as a convenience wrapper over update_inventory_item, guiding when to choose this tool over the alternative. Also specifies the OAuth scope and ownership requirement, making usage conditions clear.

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?

Goes far beyond the readOnlyHint annotation by disclosing rate limits ('100 requests/hour per IP'), the lack of authentication, behavioral nuances of `relevance_score` (including calibration caveats), null-priced row handling, and exact runtime expectations for each mode. No contradiction with annotations.

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

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

Although long, every sentence earns its place given the tool's complexity. The use of bold headers, bullet points, and clear mode breakdowns makes it scannable and front-loaded with the most critical search-instruction. It is structured for practical agent use, not padded.

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

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

Completely covers return values (list of products with fields), edge cases (relevance score pitfalls, null prices, cross-language), and workflow advice (use `get_product` after). With an output schema present, the description still adds key context about how to interpret results and when to trust scores.

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?

With 0% schema description coverage, the description carries full responsibility and excels: it explains every one of the 11 parameters with meanings, defaults, and tips (e.g., `min_price` null-priced behavior, `sort_by` price ordering caveat, `super_search` multi-step process). It adds substantial value beyond the bare schema.

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

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

The description opens with a specific verb and resource: 'Search Partle's product catalog by name or description.' It clearly differentiates from sibling `search_stores` by noting 'Prefer over `search_stores` when the intent is product-led', and from `get_product` as a follow-up for full details.

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

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

Provides explicit when-to-use guidance: 'Use this when the user asks to find a specific product or browse products matching a query.' Includes a CRITICAL SEARCH INSTRUCTION on transforming user queries into product phrases, and distinguishes default vs. `super_search` modes with concrete examples and alternatives like `get_product` and `search_stores`.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial context beyond that: 'Read-only. No authentication. Rate-limited to 100 requests/hour per IP.' It also discloses geocoding behavior ('lat/lon (when geocoded)') and that `product_count` enables 'competitive-landscape sizing without a separate `search_products` round-trip.' This goes well beyond the annotation signaling.

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?

Although longer than a two-sentence description, it is tightly organized with sections for usage, parameters, and return values. Every sentence adds functional value—no filler. The structure guides the reader smoothly from purpose to invocation details.

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 moderate complexity plus an output schema, the description is complete: it explains return fields, optional geocoding, the `id` cross-reference to `search_products(store_id=…)`, and rate limiting. There is no missing context that would leave an AI agent guessing.

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% (no descriptions in the input schema), but the description compensates fully: 'query: Free-text search over store name and address. Omit to list all stores in default order.' and 'limit: Max results (1–50, default 20).' This adds exact meaning and constraints that the schema omits.

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

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

The description opens with a specific verb+resource: 'Search or list stores in the Partle marketplace.' It immediately distinguishes itself from product-led search by stating 'store-led questions... rather than product-led ones (use `search_products` for that).' This exactly meets the standard for purpose clarity and sibling differentiation.

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

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

It explicitly states when to use this tool vs. the alternative: 'Use for store-led questions... rather than product-led ones (use `search_products` for that).' It also covers the no-query browsing case: 'Pass no query to browse the whole catalog.' This is textbook usage guidance with named alternatives.

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

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

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses critical behavioral details: 'Read-only. No authentication. Rate-limited 100 req/hour per IP.' It also explains response semantics, such as how the consumer should use the contact field and that Partle doesn't broker conversations. This adds real value beyond the annotations.

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

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

The description is well-structured with a high-level summary, usage guidance, Args and Returns sections. Every sentence adds necessary detail — from the demand-side framing to the deprecated 'title' field. There is no repetition of schema data or filler. It is appropriately sized for a tool with this behavior.

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

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

The description covers everything an agent needs: purpose, usage, auth/rate limits, parameter semantics, return field list, and behavioral notes (contact usage, markdown, deprecated field). Despite the output schema existing, the description adds extra context about the human/consumption flow. It is complete for a complex, publicly-facing read 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?

The input schema provides only names and basic types with no descriptions (schema coverage 0%), so the description carries the full burden. It does this excellently: explains query as a case-insensitive substring over name+description, with omission listing all newest first; gives concrete limit range (1–100, default 20); and defines offset as pagination. This fully compensates for the sparse schema.

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

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

The description opens with a clear, specific verb and resource: 'Browse public buy requests' — what users are looking to buy. It further distinguishes the tool as 'The demand side of Partle,' setting it apart from supply-side tools like search_products. The purpose is unmistakable.

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 explicitly tells when to use this tool: 'when an agent wants to offer matches (cross-reference open requests against search_products and surface hits) or just survey unmet demand.' It also clarifies that buy requests are sales-facing ads, separate from private inventory, preventing misuse. This is exemplary usage guidance with an explicit alternative.

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?

Discloses auth requirements (OAuth with required scope, fallback api_key), attribution to account, deduplication within 24 hours, and the fact that each call adds a row and pages the maintainer. Also explains the api_key override behavior and failure conditions for invalid/revoked tokens. This goes well beyond the sparse annotations.

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

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

The description is long but well-structured with clear sections, bold headers, and bulleted lists. Every line adds value, covering scope, auth, behavior, and parameters. The organization makes it easy to scan, and there is no redundancy.

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

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

Given no output schema, the description explains the return format (success and error responses). It also covers auth flows, rate limiting, validation, dedup behavior, and scope boundaries. The tool is contextually complete for an agent to understand when and how to invoke it correctly.

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

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

Even though schema description coverage is 0%, the Args section thoroughly documents both parameters. Feedback is described with length limit and guidance on specificity. api_key is described with its optionality, when it is used, override behavior, and failure conditions. This fully compensates for the empty schema descriptions.

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

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

The description clearly states the tool's purpose: reporting problems with the Partle marketplace API/MCP itself. It explicitly lists what the tool is for and what it is NOT for, distinguishing it from sibling tools that handle inventory, products, and searches.

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

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

Provides explicit when-to-use and when-not-to-use guidance, including specific examples like unclear tool descriptions, malformed responses, missing catalog categories, and poor search relevance. Also clearly states exclusions such as general complaints, fabricated API keys, and requests for maintainers to do user work.

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

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

The description discloses auth requirements, ownership checks with 404 behavior, idempotency (also in annotations), and api_key override semantics. It also describes the return/error shape. This adds substantial behavioral context beyond the annotation hints.

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 well-structured with front-loaded purpose, followed by auth/idempotency details, an Args block, and Returns. Every sentence conveys necessary information without filler or repetition.

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 16-parameter patch tool with no output schema, the description covers auth, ownership, idempotency, parameter behavior, and return/error format. The only minor gap is relying on add_inventory_item to define the remaining parameter semantics, but the general 'only provided fields change' rule covers the core PATCH behavior.

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%, but the description explains the critical PATCH semantics: 'Only provided fields change' and 'omit any field you don't want changed.' It gives detailed meaning for item_id and api_key. For the remaining fields it defers to add_inventory_item, which is reasonable but not fully self-contained.

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

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

The description opens with 'Patch an existing inventory item. Only provided fields change.' This uses a specific verb (patch) and resource (existing inventory item), clearly distinguishing it from create/delete/lifecycle siblings. It even references mark_for_sale and mark_sold as specialized alternatives, cementing its unique role.

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 states required OAuth scope, ownership prerequisite, and explicitly directs users to mark_for_sale/mark_sold for lifecycle operations. It also explains the api_key fallback/override behavior. This gives the agent clear when-to-use and when-to-use-alternative 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?

Beyond annotations, it discloses partial-update semantics (omitted fields preserved), idempotency, ownership requirement, error conditions, and auth fallback behavior. No contradiction with annotations; it enriches them.

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

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

The description is well-organized with Args/Returns sections, but contains minor redundancy (partial-update behavior stated twice). Otherwise every sentence adds value.

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?

Covers purpose, auth, ownership, errors, return format, and all 7 parameters. Given no output schema, the Returns section adequately describes the full updated record or error object.

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?

With 0% schema description coverage, the description fully explains each parameter: product_id sourcing, price max and currency example, api_key override behavior, and omit-to-leave-unchanged 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 opens with 'Update an existing product listing,' a specific verb+resource statement. It differentiates from siblings by explicitly directing creation to create_product.

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

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

It explicitly states when to use (updating existing products, not creating) and names create_product as the alternative. Also provides clear authentication guidance (OAuth scope preferred, api_key fallback) and ownership prerequisite.

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 provide basic flags (readOnlyHint false, openWorldHint true, idempotentHint true), but the description adds meaningful behavioral detail: authentication requirements, OAuth scope preference, api_key fallback and override semantics, server-side fetching/storage, and error response format. This adds context beyond the annotations.

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

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

The description is long but highly structured with bold headings, a clear opening, and a code block for the alternative path. Every sentence carries purpose: purpose, auth, when to use/not use, parameters, and return value. It is front-loaded and earns its length.

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 tool with no output schema, the description provides complete context: purpose, usage boundaries, auth details, parameter semantics, and return value mention. It even explains how to accomplish the same goal in a different way, leaving no gaps.

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

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

Schema has 0% description coverage, but the Args section fully documents all three parameters: product_id, image_url, and api_key, including edge cases like api_key overriding a narrowly scoped OAuth token. This fully compensates for the empty schema descriptions.

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

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

Description opens with a specific verb and resource: 'Attach an image to an existing product by giving Partle a public URL to download the image from.' It clearly distinguishes this tool from siblings like delete_product_image and create_product, and the title matches the tool's function.

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

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

Explicit 'When to use this tool' and 'When NOT to use this tool' sections provide clear contexts, including an alternative HTTP endpoint and code example. It directly states when to prefer the tool vs. the sandbox multipart upload, which is excellent guidance.

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