Teppek

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

Discloses behavior well beyond the annotations: moderation hold with status "pending", credit refund policy including the prohibited/spam forfeiture exception, the ACTIVE_LISTING_LIMIT_REACHED error carrying a pay_url, and the image_not_uploaded failure mode. None of this is derivable from destructiveHint=false / openWorldHint=true, and nothing contradicts those 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?

Purpose and the location constraint are front-loaded, and every sentence carries information an agent needs (entitlements, moderation, refunds, image flow, auth). It is dense and slightly run-on across the credits/moderation sentences, but there is no filler to cut.

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

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

An output schema exists, so return values need no explanation, yet the description still covers error paths, moderation lifecycle, and the auth prerequisite. For a 9-parameter, nested-object, non-idempotent write tool this is complete enough to call correctly on the first attempt.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds workflow-level meaning the schema cannot — that `location` takes coordinates only and must be geocoded first, and that `images` keys must come from request_image_upload with bytes already uploaded. It adds less on `details` and `price`, but the cross-tool parameter dependencies are genuinely extra value.

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

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

Opens with a specific verb+resource ("Publish a listing") plus scope (4 verticals, 12 roles), which cleanly separates it from update_listing, renew_listing, and set_listing_status. An agent can identify the create-path tool without opening any schema.

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

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

Gives explicit preconditions and named alternatives: geocode before calling because free-text addresses are rejected, call get_entitlements to check slots/credits, call request_image_upload before passing `images`, and surface authorize_url before retrying on AUTH_REQUIRED. This is a full when-and-with-what sequence, not just a hint.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is structured. The description adds genuinely new context — soft-delete rather than hard delete, owner-only authorization, no credit refund — but does not say what happens to the listing's conversations, images, or visibility after deletion.

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

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

Three short sentences, front-loaded with the action and scope, then constraints. Every sentence carries information; no padding or repetition of the schema.

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

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

An output schema exists so return values need no explanation, and the description covers the destructive-but-recoverable nature, authorization, and credit implications. It leaves some ambiguity about post-deletion state of related resources, which matters for a destructive tool.

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

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

Schema coverage is 100% and the listing_id schema entry already documents the id format, source fields, and an example. The description adds nothing beyond naming the parameter, which is the expected baseline.

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

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

States a specific verb and resource ('Delete ... listings') plus the key qualifier 'soft-delete', which distinguishes it from a hard delete and from sibling status-changing tools like set_listing_status. Ownership scoping ('USER'S OWN') further narrows it.

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?

Implies usage through the ownership restriction and notes the side effect about credits, but never states when to prefer it over set_listing_status or update_listing, nor any exclusions or prerequisites beyond ownership.

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 indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds important context beyond annotations: it discloses the side effect of marking incoming messages read and the authorization constraint that only threads the user participates in are returned. This goes beyond structured data without contradicting it.

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 concise sentences, front-loading the core action and side effect. Every sentence earns its place by conveying 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?

Given the tool's simplicity (one parameter, output schema present), the description covers the essential aspects: purpose, side effect, and authorization scope. An agent has enough to invoke it correctly without needing return value details.

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

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

Schema coverage is 100%, so the thread_id parameter is fully documented in the schema, including its UUID format and example. The description only restates 'by thread_id', adding no additional semantic 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 states a specific verb ('Read') and resource ('message conversations'), with a clear scope ('user's OWN') and access method ('by thread_id'). It distinguishes from list_conversations by referring to a single conversation, but does not explicitly name the sibling alternative.

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

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

Usage is implied: use it to read a specific conversation by thread_id. However, there is no explicit guidance on when to use this tool versus list_conversations or reply_to_conversation, nor any when-not conditions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value by disclosing the decision branch at the limit — whether the user can pay from wallet credit or should be sent to checkout via pay_url. It does not discuss cost of calling, caching, or freshness of the balance, which keeps it below 5.

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

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

The action and its timing constraint are front-loaded in the first clause, and the second sentence carries only the branch-relevant information about pay_url. No sentence restates the name or wastes space.

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 zero parameters and an output schema present, the description only needs to convey purpose and the actionable interpretation of the result, both of which it does. An agent knows when to call it and what to do with the limit-reached case.

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

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

The tool takes zero parameters and the schema is trivially complete, so the baseline of 4 applies; there is nothing parameter-wise the description could usefully add.

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

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

States a specific verb and resource ('Check the user's publishing entitlements') and then enumerates exactly what is returned: tier, max vs current active listings, remaining slots, wallet credit, per-listing cost, can_create_listing. This is unmistakably distinct from sibling mutations like create_listing or renew_listing, which the agent would otherwise be tempted to call directly.

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 capitalized 'BEFORE attempting to publish' gives clear temporal/conditional guidance that ties this call to the publish flow. It stops short of naming the sibling tool it gates (create_listing) or stating when-not to call it, so it is strong context rather than full routing.

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 openWorldHint=true, so the safety profile is covered. The description adds useful scope ('ONE' listing, includes the Teppek contact route) but says nothing about behavior on an unknown/stale id, id reuse across sources, or rate limits — minor but real gaps for a lookup tool.

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

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

A single tight sentence with the resource and scope front-loaded, followed by the routing condition. No filler, no repetition of the title or annotations.

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

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

With an output schema present, return values need no explanation, and the annotations plus a 100%-covered single parameter leave little else to disclose. The only gap is what happens on a missing or invalid listing_id, which the description omits.

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

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

Schema description coverage is 100% and the single parameter is fully documented in-schema, including its provenance ('id field of search_listings, semantic_search or list_my_listings') and a concrete example. The description only restates 'by id' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch the full detail of ONE Teppek listing by id') and enumerates the returned fields (title, description, price/salary, location, contact route). The 'ONE' emphasis and the 'after search_listings' framing clearly separate it from the bulk siblings search_listings, semantic_search and list_my_listings.

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 routes the agent: 'Use after search_listings to show, summarize or compare a specific job, home, vehicle or service the user picked.' It names the prerequisite sibling and the intent (show/summarize/compare one item), though it does not state an explicit exclusion such as 'do not use to browse multiple listings — use search_listings 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: scoping is derived from the authenticated agent key ('only ever this user's threads') and results arrive newest-first — both call-behavior facts the schema does not carry.

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

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

Two tight sentences: identity and scope first, then the cross-reference to get_conversation. No redundancy with the schema, no filler, nothing to trim.

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?

Output schema exists, so return values needn't be described, and the schema fully covers paging parameters. With annotations handling safety and the description handling scoping, ordering, and the follow-up tool, an agent has everything needed to invoke this 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 100% — limit (1-50, default 20) and offset (paging, with a worked example) are fully documented in the schema. The description adds nothing about the parameters themselves, so baseline 3 applies; 'newest first' implies the sort key but not the paging 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?

Names a specific verb+resource ('List ... listing-message conversations') and immediately bounds the scope to the caller's own threads (started, or received as a listing owner). It also states ordering ('newest first') and edges out the sibling get_conversation, so an agent can distinguish it without opening any schema.

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

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

Explicitly routes the agent onward: 'Use get_conversation to read a thread's messages,' which cleanly separates listing threads from reading one. It also clarifies that no user filter is needed. It stops short of stating when not to use it (e.g., searching across listings), so it's not a full when/when-not contract.

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 openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: results are newest-first, scoped to the authenticated agent key, and can never leak other users' listings. Return shape is left to the output schema, which exists.

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

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

Three short sentences, front-loaded with the ownership scoping that is the tool's defining trait. The status sentence partially duplicates the schema's status description, so a small amount of text is not strictly earning 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?

With annotations, a full output schema, and 100% parameter coverage, the description covers what the agent needs: who the results belong to, ordering, and status filtering. Pagination is fully handled by the schema, so nothing critical is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the status enum and pagination semantics. The description's status examples largely restate the schema's own status description, adding only mild framing about 'awaiting moderation'.

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

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

States a specific verb and resource ('List the user's OWN listings'), plus scope ('any status') and ordering ('newest first'). The auth-key resolution sentence makes it unmistakable that this is owner-scoped, distinguishing it from search_listings without needing to name the sibling.

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 directs the agent to status='pending' for moderation queues and status='rejected' for declines, which is real when-to-use guidance. It stops short of stating when to prefer get_listing or search_listings over this tool, so no explicit exclusions or alternative routing.

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 only say this is a non-read-only, non-destructive, non-idempotent mutation; the description adds the actual effect (expiry reset to 30 days from now), the cost profile (free, no credit charge), and the state-transition rules. That is substantive behavioral context beyond the structured hints, including which listing states will fail.

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

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

Front-loads the action and ownership scope, then cost, then eligibility in descending priority. Every clause carries distinct information with no repetition of the name or annotations.

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

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

With an output schema present, return values need not be explained, and the key preconditions and side effects are covered. Minor gaps remain: no mention of auth/permission requirements or what happens on a repeated renewal given idempotentHint=false.

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

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

Schema coverage is 100% and the single listing_id parameter is already documented with provenance (search_listings, semantic_search, list_my_listings) and an example. The description adds nothing about the parameter itself, so the baseline 3 applies.

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

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

States a specific verb (renew), a specific resource (a listing), and scope (one of the USER'S OWN listings), which separates it from update_listing or set_listing_status in the sibling set. The parenthetical about native listings lapsing ~30 days after posting explains what renewal means mechanically.

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

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

Gives explicit eligibility rules: expired listings return to active, while pending, rejected, sold, or draft listings cannot be renewed. It does not name alternative tools (e.g., set_listing_status) for those ineligible states, so the agent must infer the fallback.

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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the message goes to the other participant and contact routes through Teppek without exposing raw personal details. It does not add much about failure modes or duplicate-send behavior, but the annotations carry that burden.

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 action, then immediately covers usage, the alternative tool, privacy routing, and thread_id discovery. It is appropriately sized with no wasted sentences.

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 full schema coverage, annotations, and an output schema, the description provides everything an agent needs: purpose, when to use it, the sibling alternative, thread_id source, and privacy behavior. No critical context is missing.

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

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

Schema description coverage is 100%, so both parameters are already well documented with examples and constraints. The description adds the source for thread_id (list_conversations / get_conversation), but otherwise the schema does the heavy lifting, making 3 the appropriate baseline.

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

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

The description states a specific verb and resource: continue an existing message thread by thread_id, with the message going to the other participant. It clearly distinguishes this from send_message for first contact, so an agent can select it without opening the schema.

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

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

It explicitly says when to use this tool (follow up in an existing conversation) and when not to use it (first message to a listing found in search should use send_message). It also tells the agent where to obtain thread_id via list_conversations or get_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?

Annotations already declare the operation is not read-only, not idempotent, and not destructive; the description adds substantive behavior: the grant is short-lived, returns upload credentials, requires a PUT of raw bytes with specified headers, and triggers AI moderation before the listing goes live. There is no contradiction with 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 front-loaded with purpose, then provides the return shape and upload workflow, then closes with the moderation note. Every sentence carries useful information and there is no redundant restatement.

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 simple two-parameter schema, full schema coverage, annotations, and an output schema, the description supplies everything an agent needs: the grant workflow, how to use the returned fields, where the key goes, and the moderation gate. No critical operational detail is missing for this 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 100%, with both content_type and file_size fully documented, including the enum and 10 MB maximum. The description adds workflow context but does not add meaning beyond the schema for either parameter, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: get a short-lived upload grant for attaching a photo to a listing about to be published. It also names create_listing as the downstream consumer, which distinguishes this pre-publish upload grant from update_listing_images used for existing listings.

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 the context: use this when you need to attach an image to a listing you're about to publish, then pass the returned key into create_listing's images array. It does not explicitly mention the update_listing_images alternative or when not to use this tool, so it stops 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?

Adds a lot beyond readOnlyHint/openWorldHint: country-scoped browse only works for the career vertical (0 results elsewhere), real_estate inventory is thin so empty results are expected, price filters may be silently dropped and surface in meta.ignored_filters, and sorting is currency-naive. These are failure modes the agent could not infer from 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?

Core guidance is front-loaded, but the text is overlong and repeats the role/text_query rule twice, contains a garbled fragment ('country, category and near work without role'), and mixes mechanics, caveats and counting advice in one dense block. Every fact earns its place individually, but the packaging costs readability.

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 12-parameter, zero-required tool with a nested `near` object, the description covers the traps that matter: empty-result semantics, which filters apply in which mode, how meta.total counts multi-word queries, and how to page. An output schema exists, so return-shape detail is correctly omitted.

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

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

Schema coverage is 100% (baseline 3), but the description goes well beyond it: it explains that role is the perspective you search AS and returns the counterparty side (career_seeker for job postings, not career_employer), that country is career-only, that category slugs beat keyword counting, and that intent_type is usually redundant when role is set.

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 (find/search) and resource (live listings across four verticals), and explicitly names the sibling it is not: semantic_search for meaning-based intent. Example queries map natural-language requests onto the tool, so the agent can tell it apart from semantic_search and list_my_listings without opening a schema.

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

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

Explicit routing: exact keywords/filters go here, fuzzy/meaning-based intent goes to semantic_search. It also gives concrete when-to-use examples and states the precondition that text_query requires role, plus which filter combinations yield nothing.

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 and openWorldHint, but the description adds real behavioral context: results are restricted to ACTIVE listings, ranked by semantic similarity, and each item carries a `score`. It does not discuss cost, rate limits, or behavior on an empty/ambiguous query, which keeps it from a 5.

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

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

Front-loaded with the purpose, then the usage contrast, then the optional filter — a sensible ordering with no filler. It runs slightly long with three illustrative example queries plus additional examples carried in the schema, so a small trim would be possible.

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 read-only, three-parameter search tool with full schema coverage and an output schema, the description covers everything an agent needs: what it searches, how results are ranked and filtered, and when to choose it over the sibling. Return-value detail is delegated appropriately to the output schema.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and the enum. The description still adds value by characterizing `query` as natural-language meaning-matched intent and by explaining that `vertical` narrows to career/real_estate/vehicle/service server-side.

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

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

States a specific verb and resource ('Semantic (meaning-based) search over Teppek's live listings') and immediately qualifies the mechanism (multilingual embedding index, ranked by similarity). It explicitly contrasts with search_listings, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit routing rules in both directions: 'prefer search_listings for precise keyword/role/country/category/price filtering and exact counts; prefer semantic_search when meaning, synonyms, or fuzzy intent matter.' It also supplies concrete example queries that define the intended input class.

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 only say non-readonly, open-world, non-idempotent, non-destructive; the description goes further by disclosing that contact is mediated through Teppek so raw personal details are never exposed, that external listings return a redirect rather than a thread, and that anonymous calls fail with a specific error and remediation flow. That is substantive behavioral context beyond the structured fields.

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

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

Front-loads the core action and the sibling distinction in the first sentence, then layers edge cases in descending priority. It is dense and em-dash-heavy and slightly long, but no sentence is filler — the redirect and auth clauses both carry needed 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?

With an output schema present, return-value detail is not required, yet the description still explains the two non-obvious outcomes (redirect for external listings, AUTH_REQUIRED + authorize_url) that an agent must handle. Nothing blocking a correct call is missing.

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

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

Schema coverage is 100% and both params are documented in-schema (body length limit, listing_id provenance from search_listings/semantic_search/list_my_listings). The description adds only the notion that the listing identifies the owner's thread target, which is largely implied by the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('START contact with the owner of a Teppek LISTING on the user's behalf') and immediately scopes it as the primary first-contact path with no price-offer/accept/reject flow. It also names the contrasting sibling (reply_to_conversation) so the agent can distinguish it without opening either schema.

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

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

Explicit routing rule: use this to open a NEW thread, use reply_to_conversation when a thread_id already exists. It also covers the external-feed case (redirect instead of thread) and the unauthenticated case (AUTH_REQUIRED with authorize_url, then retry), which are exactly the branch conditions an agent needs.

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 non-destructive, idempotent, non-read-only behavior, so the bar is lower; the description adds real value with 'Free — no credit charge' and the hard constraint that moderation states cannot be set. It stops short of describing failure behavior (e.g. setting active on an already-active listing) or what happens to the listing's visibility/searchability.

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 dense sentences, front-loaded with the action and scope, followed by cost and constraints. No filler or restatement of the tool name.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. The cost note and state-transition preconditions fill the remaining gaps; only error/edge-case behavior is left implicit.

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

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

Schema coverage is 100% and the enum already documents status semantics, so the description's status explanation is largely duplicative. The only added semantics is the ownership restriction implied by 'USER'S OWN listings', which the schema's listing_id description does not state.

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 (change lifecycle status) applied to a specific resource (one of the USER'S OWN listings), and enumerates the three target states. Ownership scoping plus the 'cannot set moderation states' line clearly separates it from delete_listing and update_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?

Explains each state's meaning in actionable terms ('hide it (take it offline)', 're-activate a hidden one') and the precondition for reactivation (previously approved, currently hidden). It does not, however, name sibling alternatives such as delete_listing or renew_listing to route the agent explicitly.

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 non-obvious side effects the annotations cannot convey: title/description/location/details edits re-trigger AI moderation, the listing drops to 'pending' and goes offline until cleared, while price/currency-only edits stay live. It also states the edit is free (no credit charge) and is owner-restricted. Consistent with readOnlyHint=false, destructiveHint=false, idempotentHint=true.

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

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

Four dense sentences, each doing distinct work: scope, permissions/immutability, cost, and the moderation consequence with its price/currency exception. Front-loaded with the highest-value information and no filler.

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

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

For a 7-parameter mutation tool with nested objects, an output schema, and full annotations, the description covers everything an agent needs to call it correctly: identity, ownership, editable vs fixed fields, cost, and the moderation/availability consequence. Remaining details live in the rich schema.

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

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

Schema coverage is 100%, so per-parameter detail is already carried by the schema (including the detailed vertical-specific `details` keys). The description still adds value by enumerating the editable field set up front and by declaring vertical/intent_type/role non-editable despite additionalProperties=false. It stops short of restating per-parameter formats, which is appropriate.

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

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

Opens with a specific verb+resource ("Edit fields ... on one of the USER'S OWN listings"), enumerates the editable fields, and anchors identity to listing_id. It also explicitly separates itself from create_listing for vertical/intent_type/role changes, so an agent can route between them without opening the schema.

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

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

States the precondition ("Only the owner can edit"), what cannot be changed here and the alternative that does it ("publish a new listing to change those"), and the cost condition. Clear when-to-use and when-to-instead-go-elsewhere 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?

Goes well past the annotations by disclosing the moderation consequence (adding any image re-triggers AI moderation and the listing returns to 'pending'), the asymmetric effect of removal (live stays live; pending/rejected requests a new verdict), the specific failure mode, and the cost (free, no credit). These are exactly the side effects an agent cannot infer from readOnlyHint=false / 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?

Front-loads the operation and scope, then the workflow, then the side effects, then cost — a sensible priority order. Every clause carries information; nothing is repeated from the schema or annotations.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining risk surface: moderation state transitions, total-image cap, upload prerequisite, failure mode, and pricing. Nothing needed to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: `add` entries must be keys returned by request_image_upload with bytes already uploaded, and the 6-image cap is a listing-wide total rather than a per-call limit. It is marginally less explicit about `remove` keys being on-listing, though that is stated.

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 precise verb pair (add and/or remove) plus the resource (photos) and the scope constraint (one of the USER'S OWN existing listings, max 6 total). That scoping cleanly separates it from update_listing and from request_image_upload without needing to open either schema.

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

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

Gives an explicit ordered workflow: call request_image_upload per new image, upload the bytes, then pass the returned keys in `add`. It names the prerequisite tool directly and warns that a key with no uploaded file fails with image_not_uploaded, so there is no ambiguity about sequencing or the alternative path.

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