Teppek

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

With no annotations, the description carries full behavioral burden and excels. It discloses credit consumption, AI moderation, 'pending' status, refund policy (including exceptions for prohibited/spam content), and photo moderation. It also warns about location format. This is exemplary transparency for a mutating 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?

Three dense sentences, front-loaded with purpose. Every sentence adds critical information: location constraint, moderation/credit behavior, and image workflow. No redundancy or fluff. Efficiently structured.

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

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

Given the tool's complexity (9 params, nested objects) and that an output schema exists, the description covers all non-obvious aspects: verticals/roles scope, coordinates requirement, credit/moderation behavior, and image upload prerequisite. It does not need to explain return values. Complete for a create 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 only 33%, so the description adds meaningful semantics for `location` (must be coordinates, geocode first) and `images` (must come from request_image_upload). It reinforces role semantics already in schema. However, it does not explain `details`, `vertical`, or `description` beyond the schema, though these are more self-explanatory. The added context for the most critical params earns a 4.

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 clearly states the tool's function: 'Publish a listing on behalf of the user across any of the 4 verticals and 12 roles.' This is a specific verb+resource, and it distinguishes the tool from siblings like update_listing and delete_listing. It also clarifies scope (verticals/roles), leaving no ambiguity about what it does.

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 context for when to use the tool: geocode location first, request image uploads before attaching photos, and expect credit consumption/moderation. It does not explicitly name alternative tools or state 'when not to use,' but the constraints given effectively guide correct usage. Lacks explicit exclusions, preventing a 5.

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

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

With no annotations, the description fully bears the burden of behavioral disclosure. It reveals the soft-delete nature, ownership restriction, and financial consequence (no credit refund), which are critical behavioral traits beyond the simple schema. This is exceptional transparency for a deletion tool.

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

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

The description is two sentences, front-loaded with the primary action, and every word adds value. It avoids redundancy and presents all key information (action, ownership, soft-delete, refund policy) efficiently.

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 tool with an output schema, the description is complete. It covers what the tool does, preconditions (ownership), and postconditions (soft-deleted, no refund). No critical gaps remain.

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

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

The schema only defines listing_id as a string with length constraints. The description adds meaningful semantics by clarifying that the listing_id must belong to the user's own listing, and that the listing is already published. This compensates well 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 clearly states the verb ('Delete'), the resource ('one of the USER'S OWN listings'), and the scope ('by listing_id'). It explicitly notes it is a soft-delete and differentiates from siblings like set_listing_status by emphasizing ownership and deletion rather than status changes.

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 context for when to use the tool ('Delete one of the USER'S OWN listings'), including a prerequisite ('Only the owner can delete') and a consequence ('No credit is refunded'). However, it does not explicitly name alternative tools or scenarios where a different tool (e.g., set_listing_status) would be preferred.

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 a non-obvious side effect: 'marks incoming messages read'. It also states the access scope ('Only threads the authenticated user participates in are returned'). This goes beyond a simple read and is genuinely helpful.

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 concise sentences front-load the core action ('Read one...') and then add the important side effect and access constraint. Every word earns its place with no filler.

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

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

The tool is simple (one parameter) and has an output schema (not shown), so the return format is likely covered. The description covers the critical side effect and access scope. It does not mention error cases (e.g., not found, forbidden), but this is not essential given the explicit participation constraint.

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 sole parameter thread_id is clear from its name and the description says 'by thread_id', but it does not explain how to obtain the ID or provide format details beyond the schema's min/max length. With schema description coverage at 0%, the description adds minimal semantic value beyond the parameter name itself.

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 'Read' with a clear resource 'one of the user's OWN message conversations' and identifies the key identifier 'by thread_id'. It also states the inclusion of messages, making it distinct from siblings like list_conversations (which lists all) and reply_to_conversation (which writes).

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 clear context that this is for reading a single conversation by ID, and adds a constraint about authentication/participation. However, it does not explicitly name alternatives like list_conversations for finding thread IDs or say when not to use this tool.

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

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

With no annotations, the description carries the burden for behavioral disclosure. It details specific return fields (membership tier, max/current listings, remaining slots, wallet balance, credit cost, can_create_listing) and explains behavior when the limit is reached (wallet vs checkout). It implies a read-only check but does not explicitly state side effects or auth requirements, which is a minor gap.

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 compact yet informative, with two sentences that front-load the purpose and provide necessary details on fields and edge-case behavior. Every sentence earns its place 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?

Given the tool has no parameters and an output schema exists, the description still adds valuable context about when to use it and what the response indicates about paying vs. checkout. It is fully complete for a getter/check tool and leaves no critical 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?

The tool has zero parameters, so the schema shows nothing to document. As per baseline, a score of 4 is appropriate when no parameters exist, and the description correctly focuses on outputs and usage rather than params.

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 checks user publishing entitlements with specific attributes (membership tier, listings, wallet credit), distinguishing it from sibling tools like create_listing or update_listing. The verb 'Check' and resource 'entitlements' make the purpose 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?

The description explicitly instructs to use this tool 'BEFORE attempting to publish', providing clear timing guidance. It does not explicitly name alternative tools or exclusionary conditions, but the context is strong enough for correct selection among 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?

With no annotations, the description carries the full burden. The verb 'Fetch' clearly implies a read-only operation, and listing the returned fields adds context. It doesn't mention error cases, auth, or rate limits, but for a simple get-by-id tool, the behavior is sufficiently transparent.

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, front-loaded with the main purpose, and no filler. The em-dash list of fields is compact yet informative.

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

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

With an output schema present, return values need no elaboration. The description covers purpose, usage, and scope. Minor omissions like handling of non-existent ids are not critical for a fetch-by-id tool.

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

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

The schema has no descriptions (0% coverage), so the description must compensate. It says 'by id' and instructs to use 'after search_listings', meaning the listing_id comes from search results. This adds practical context beyond the bare schema property 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?

The description clearly states the tool fetches one listing by id, naming the resource (Teppek listing) and the exact fields returned (title, description, price/salary, location, contact route). It is easily distinguished from sibling tools like search_listings, which lists many.

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 when to use: 'Use after search_listings' for showing/summarizing/comparing a specific item. This provides clear workflow context and implicitly identifies search_listings as the alternative for browsing.

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 provided, the description discloses that results are limited to the user's own threads, resolved from the 'authenticated agent key', and sorted newest first. This adds meaningful constraints beyond the generic 'list' verb, though it doesn't explicitly confirm read-only behavior beyond the word 'List'.

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

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

The description is exactly two sentences, front-loaded with the main verb and resource, and includes a useful pointer to a sibling tool. No extraneous 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 the presence of an output schema, the description doesn't need to explain return values. It covers scope, ordering, and the follow-up tool, though pagination is left to the schema, making the description slightly incomplete for a list endpoint.

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

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

The description contains no mention of the limit or offset parameters, and schema coverage is 0%, so it fails to compensate for the schema's documentation gap. It offers no additional meaning beyond the schema's defaults and constraints.

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 specifies the action ('List'), the resource ('the user's OWN listing-message conversations'), and adds scope clarification ('threads they started, or received as a listing owner') and ordering ('newest first'). This clearly distinguishes it from sibling tools like list_my_listings (which lists listings) and get_conversation (which reads a thread).

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 directs to 'Use get_conversation to read a thread's messages', providing a clear alternative for a follow-up action. However, it does not mention exclusions such as searching or filtering across other users' conversations, so while context is clear, it lacks explicit when-not guidance.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that results are resolved from the authenticated agent key and scoped to that user, and that ordering is newest first. These are key behavioral traits beyond what the schema shows. It does not explicitly state read-only behavior, but 'list' implies it, and no side effects are mentioned.

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 three concise sentences with no filler. The primary purpose is front-loaded, followed by key scoping behavior and then practical usage tips. Every sentence earns its place.

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

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

Given this is a simple list tool with an output schema, the description covers the essentials: purpose, ownership scoping, ordering, and status filter guidance. It lacks explicit pagination behavior (e.g., how offset works with 'newest first'), but that is likely inferable. It does enough to be considered complete for this complexity level.

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 33% (only 'status' has a description), so the description should compensate. It adds meaning for status by explaining pending and rejected, but does not explain limit or offset semantics. It does mention 'newest first' which indirectly relates to ordering but not pagination. Overall, it partially compensates but leaves the standard pagination params undocumented.

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 lists the user's own listings with a specific verb and resource, and emphasizes ownership scope ('own listings', 'only ever returns this user's listings'). It also specifies ordering (newest first), distinguishing it from sibling tools like search_listings or list_conversations.

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

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

The description gives explicit guidance for using status filters ('pending' for moderation, 'rejected' for declined), which is practical. It also implies when to use this tool by highlighting that it returns only the authenticated user's listings, differentiating it from broader search tools. However, it does not explicitly name alternative tools or state when not to use it.

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 transparency burden. It discloses cost (free), the 30-day extension, the lapse behavior, and which states cannot be renewed. It could add more about error conditions or side effects, but the key behavioral traits are covered.

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 three tight sentences, front-loaded with the core purpose, then adding cost and eligibility constraints. Every sentence earns its place with 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 simple single-parameter tool with an output schema, this description is complete. It covers purpose, effect, cost, ownership, and state restrictions, enabling an agent to select and invoke it correctly without additional context.

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, listing_id, with no description and 0% schema coverage. The description adds an important ownership constraint ('USER'S OWN listings') and eligibility rules, but never explicitly names listing_id or explains its 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 uses a specific verb ('renew') with a specific resource ('one of the USER'S OWN listings') and clearly states the effect (extend expiry 30 days). This clearly distinguishes it from sibling tools like update_listing or set_listing_status.

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 clearly states when to use (renew own listings) and specifically lists when-not cases (pending, rejected, sold, draft cannot be renewed). It does not explicitly name alternative tools, so it falls just short of a 5.

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

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

With no annotations, the description carries the burden and adds useful behavioral context: the message goes to the other participant, contact routes through Teppek, and raw personal details are never exposed. The phrase 'USER'S OWN' also implies an ownership/permission boundary for the conversation.

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

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

Three sentences, front-loaded with the core action and resource, then scenarios, privacy routing, and how to find the identifier. Every sentence earns its place with no redundant detail.

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

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

For a simple two-parameter write tool with an output schema, the description covers purpose, ownership, recipient, privacy, and how to find thread_id. It does not introduce an explicit alternative, but the usage context is sufficiently clear.

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 50% because thread_id lacks a description. The description compensates by explaining that the reply is threaded by thread_id and by telling the agent to find thread_id via list_conversations/get_conversation. Body semantics are already covered in 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 opens with a specific verb and resource: 'Reply into one of the USER'S OWN message conversations by thread_id' and clarifies the recipient as 'the other participant.' It also distinguishes this from a generic send by centering on an existing conversation thread.

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 use context: works whether the user is the listing owner answering or the inquirer following up, and tells the agent how to obtain the required thread_id via list_conversations/get_conversation. It does not state explicit when-not-to-use or name alternatives like send_message, so not a 5.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior, and it does so thoroughly. It explains that the grant is short-lived, that the tool only issues the grant (actual upload is a separate POST), and that images undergo AI moderation (content safety + consistency) before publication. It also details the exact return fields, which is significant behavioral context beyond structured data.

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 three sentences, each earning its place. The first sentence states purpose and scope, the second gives the return contract and exact next steps, and the third discloses a critical behavioral constraint (AI moderation). No filler or redundancy; highly structured and 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?

Even though an output schema exists, the description goes beyond what structured data provides: it explains the workflow (get grant → POST bytes → pass key), the moderation check, and the integration with create_listing. It convincingly covers the tool's lifecycle and constraints, making it complete for an agent to select and invoke 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 0%, so the description must compensate for parameter meaning, but it does not directly explain content_type or file_size. While the schema provides enums and size limits, the description omits how these parameters influence the upload grant (e.g., validation or URL generation). The only implicit hint is that the tool is for uploading images, but this is too weak to compensate for the lack of explicit parameter guidance.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('short-lived upload grant') and its purpose ('attach a photo to a listing'). It explicitly distinguishes this from sibling tools by focusing on the upload grant workflow and its connection to create_listing, making it clear this is not a listing mutation or search operation.

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 clearly states when to use this tool ('to attach a photo to a listing you're about to publish') and provides a direct follow-up action ('pass the returned key in create_listing's images array'). It also notes the tool works for 'any vertical/role', removing ambiguity about scope. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of the highest bar.

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?

Despite having no annotations, the description thoroughly discloses behavioral nuances: role returns counterparty listings, empty query returns nothing, meta.total is the real match count, multi-word queries match ANY word, country-scoped browse only works for career, and meta.ignored_filters flags unapplied price filters. This fully compensates for missing 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 a dense block but front-loaded with purpose and examples, and each sentence introduces valuable detail. It is not too verbose, though it could be improved with section breaks for readability. Every sentence earns its place, so it's strong albeit slightly unstructured.

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 (12 params, nested objects, no annotations), the description covers all essential aspects: usage scenarios, data freshness, role semantics, required parameters, response meta behavior, country limitations, and ignored filters. Output schema exists, so not explaining return values is acceptable. The description is comprehensive.

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 50%, but the description adds critical semantics for parameters beyond the schema: it explains the role perspective system, text_query requirement, multi-word ANY behavior, country scoping limitation, and how ignored_filters works. This substantially elevates understanding of params like role, near, text_query, and country.

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 ('Find live jobs, homes/rentals, vehicles, or local services NEAR a place or in a city/country on Teppek'), making the tool's scope immediately clear. It also distinguishes itself from generic web search by emphasizing real-time, location-aware listings, which separates it from broad-search 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?

Provides explicit natural-language query examples ('jobs near me', 'apartments in Berlin') and states a clear preference over generic web search for real, current local listings. However, it does not explicitly compare against sibling search tools like semantic_search, so there is room for more exclusionary 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?

No annotations are provided, so the description carries full burden. It explains the output (ranked by semantic similarity with a score) and mentions it only acts on active listings. It could be more explicit about idempotency/read-only nature, but the examples and context imply safe read 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?

The description is concise yet informative, with natural language examples that aid understanding. It is front-loaded with the core purpose and usage guidance, though slightly wordy with multiple examples.

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 presence of an output schema (implied by context), the description needn't detail return values. It covers purpose, usage guidelines, and basic behavior. It could mention that the search is multilingual, but overall it is sufficiently complete for a search 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 description coverage is 67% (2 of 3 parameters have descriptions). The description adds no additional meaning beyond what's in the schema; the optional vertical filter is already described. The 'limit' parameter lacks description in both schema and description text.

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

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

The description clearly states it performs semantic search over active listings, using natural language queries. It distinguishes itself from keyword search with concrete examples, making its purpose 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?

It explicitly contrasts with sibling tool 'search_listings', explaining when to use each: semantic_search for meaning and synonyms, search_listings for precise filtering. This helps agents select the correct tool.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It transparently states that the tool opens/appends a private thread, routes contact through Teppek without exposing raw personal details, and returns a redirect for external-feed listings instead of creating a thread. This provides substantial behavioral context beyond 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?

The description is three sentences, front-loaded with the primary purpose, and every sentence adds meaningful behavioral or usage detail. There is no redundant text or unnecessary padding.

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

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

The description covers the core purpose, side effects, and edge cases (external-feed redirect) well. The presence of an output schema supplements return-value expectations. However, given the sibling tool reply_to_conversation, explicit differentiation from that tool would enhance completeness.

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% (body has a description, listing_id does not). The tool description reinforces body semantics (contact routing, privacy) and clarifies that listing_id refers to a Teppek listing, but it does not explicitly describe listing_id's format or source. The description partially compensates but leaves room for ambiguity.

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

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

The description clearly states the action ('Message the owner of a Teppek listing on the user's behalf') and identifies the primary contact path, explicitly ruling out a price-offer/accept/reject flow. However, it does not explicitly distinguish this tool from sibling reply_to_conversation, which is a closely related messaging tool.

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

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

It gives clear context for when to use this tool: as the primary contact path for Teppek listings, including behavior for external-feed listings. It implies this is the go-to for contacting owners but does not explicitly state when not to use it or mention alternatives like reply_to_conversation.

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 provided, the description carries the full burden of behavioral transparency. It discloses that the operation is free ('No credit charge'), that it cannot set moderation states, and that re-activation has strict conditions. It also implies a state mutation. It does not discuss side effects like sales proceeds or reversibility, but the key boundaries are well covered.

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 three sentences long, front-loaded with the main purpose, and contains no filler. Each sentence adds valuable information: the action and statuses, the cost, and the limitations/conditions.

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 two parameters, an enum, and an output schema, the description is sufficiently complete for an agent to correctly select and invoke the tool. It covers the primary purpose, constraints, and a key precondition. It could mention error cases or authentication requirements, but these are not essential for this level of complexity.

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 covers the status parameter with a detailed enum description, but listing_id only has length constraints. The description adds semantic meaning by clarifying that the listing belongs to the user and by explaining the condition for 'active' (requires previously approved and currently hidden). This compensates for incomplete 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 clearly states the tool's purpose with a specific verb ('Change') and resource ('lifecycle status of one of the USER'S OWN listings'). It explicitly enumerates the three supported status changes (sold, hidden, active) and distinguishes it from sibling tools like update_listing or delete_listing.

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 strong context for when to use the tool: it is scoped to the user's own listings, and it explicitly states what it cannot do ('Cannot set moderation states (pending/rejected)') and a key precondition ('re-activating only works on a listing that was previously approved and is currently hidden'). It does not explicitly name alternative tools, but the boundaries are clear enough.

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 provided, the description carries the full burden of behavioral disclosure. It reveals that editing is free, changing certain fields re-triggers AI moderation and moves the listing to 'pending', and price changes may be rejected if locked. These are non-obvious consequences critical for an agent to understand before invoking the tool.

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

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

The description is concise and well-structured, with four sentences each adding essential information: field scope, ownership and immutability, cost, moderation behavior, and price lock. It is front-loaded with the purpose and contains no filler.

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

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

Given the tool's complexity (7 parameters, nested objects) and no annotations, the description is quite complete, covering ownership, cost, moderation, and price lock. However, it omits the 'details' parameter and does not mention any prerequisites like authentication beyond 'owner only', leaving a couple of minor 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 description coverage is only 14%, so the description must compensate. It explains the impact of editing title, description, price, currency, and location, but completely omits the 'details' parameter entirely, leaving agents unaware of its existence and semantics. While it adds context for the fields it lists, the omission is a significant 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?

The description clearly states the tool's function: 'Edit fields (title, description, price, currency, location) on one of the USER'S OWN listings'. It specifies the resource (listings), the action (edit), and the ownership scope, distinguishing it from sibling tools like create_listing, delete_listing, and update_listing_images.

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 guidance on when to use this tool versus alternatives: 'Only the owner can edit' and 'vertical/intent_type/role are fixed (publish a new listing to change those)' directly name an alternative action for unsupported edits. It also warns about moderation re-triggers and price lock rejection, giving clear context for usage.

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 provided, the description carries the full burden for behavioral disclosure. It reveals critical traits: adding images causes the listing to return to 'pending' pending moderation, removing images does not, and the operation is free (no credit). This goes well beyond a generic update and gives agents necessary expectations.

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 compact—two sentences—and front-loads the core purpose and limits. Every sentence contributes value: the first states the action and constraint, the second provides the workflow and behavioral nuances. 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 the tool has an output schema (so return values need no explanation), sibling tools, and moderate complexity, the description fully covers the necessary context: ownership, sequence, moderation impact, credit cost, and image limit. It is sufficient for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 67% (add and remove have descriptions, listing_id does not). The description adds workflow context for `add` by referencing request_image_upload keys and reinforcing the moderation consequence, which complements the schema. However, it doesn't explain the listing_id parameter beyond the field name, slightly limiting full 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 clearly states the tool's purpose: 'Add and/or remove photos on one of the USER'S OWN existing listings (max 6 total).' It identifies the specific verb (add/remove), the resource (photos on a listing), and ownership restriction, distinguishing it from siblings like update_listing and request_image_upload.

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: 'First call request_image_upload for each new image and upload the bytes, then pass the returned keys in `add`.' It also notes the behavioral distinction that adding images re-triggers moderation while removing does not, giving clear context for when to perform each action.

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