Neeed Directory

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, and the description reinforces this with the explicit 'It records nothing' plus the hand-off to the edit-page Verify action. It also discloses the three possible outcomes (found, missing, inconclusive), which the annotations do not convey. It does not discuss the external fetch/timeout behavior implied by openWorldHint.

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 core action and its outcome set, followed by the important non-mutation caveat. Wording is a bit tangled ('on one of your Free listings' sites now') and could be tightened.

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, the description needn't spell out return values, and it still usefully previews the found/missing/inconclusive results and the returned markup. For a one-parameter read-only check, the agent has enough to call it correctly; only external-site failure 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 description coverage is 100% and the single slug parameter is documented in-schema with its source ('from my_listings'), so the baseline is 3. The description never mentions the slug or its format, adding nothing 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?

States a specific verb and object: it looks for the Neeed badge on one of the user's Free listing sites and answers found/missing/inconclusive. That is clearly distinct from siblings like fetch, my_listings, or update_listing, though it never names those siblings to sharpen the boundary. The typo 'Neeed' and the loose phrase 'one of your Free listings' sites' slightly blur an otherwise precise statement.

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 real context: run it to check the badge now, and if you want the link made dofollow or a hidden listing restored, the maker presses Verify on the listing's edit page instead. It thus routes the agent away from expecting this tool to mutate anything. It stops short of explicitly contrasting with sibling tools like update_listing or fetch.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds one genuinely non-obvious behavioral trait: only approved products are retrievable, and it sketches the payload (title, plain-text card, url, website/category/pricing metadata). It doesn't say what happens for an unknown or unapproved slug.

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 resource and key, then the return contents. Nothing is redundant with the tool name and no filler is present.

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

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

With an output schema and full annotation coverage, the description only needs to convey scope and how to obtain the argument, which it does. The one gap is not-found / not-approved behavior for a slug that yields nothing, which matters 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?

Schema coverage is 100% and the single `id` property already documents itself as 'a product slug from search or list_products'. The description restates that same fact rather than adding formatting, length, or lookup semantics 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?

The description names a specific resource (one approved product on Neeed Directory) and its retrieval key (id / slug), plus what it returns, which is far more than the generic name 'fetch' conveys. It also points to search and list_products as the source of the identifier, implicitly distinguishing this from those listing tools. Slightly fragmentary wording ('One approved product ... by id') keeps it below a 5.

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

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

It tells the agent where the id must come from ('the slug from search or list_products'), which is a useful precondition that prevents a common misuse. It stops short of an explicit when-to-use statement (e.g. 'call this when you need full detail for a known product rather than a list of candidates').

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavior: the result set is exhaustive ('Every category') rather than paginated or filtered, and the count field reflects only approved products — a nuance not derivable from annotations or 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?

Two sentences, no filler: the first defines output and scope, the second defines the downstream workflow. The most load-bearing information (what you get back) is front-loaded.

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

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

For a zero-parameter enumeration with an output schema and full annotation coverage, nothing an agent needs is missing: scope, fields, and next step are all stated. Return-value formatting is already handled by the output schema, so the description need not repeat it further.

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?

Zero parameters, so the baseline is 4; the schema is empty and there is nothing to misdescribe. The only parameter mentioned belongs to the sibling tool (list_products' category slug), which is clearly attributed there and does not create confusion about this tool's inputs.

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

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

The description names the resource (Neeed Directory categories) and enumerates exactly what each entry contains — slug, name, approved product count, url — so an agent knows this is a full category enumeration. The verb is only implied by the name, but the scope ('Every category') is unambiguous and it distinguishes itself from list_products by pointing at it as the follow-up step.

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

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

'Pass a category slug to list_products to read its product cards' gives explicit chaining guidance: call this first, take a slug, then use the sibling. It stops short of naming when NOT to use it (e.g., versus search) or any prerequisites, so it stops at clear context rather than full when/when-not coverage.

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 readOnly/idempotent/non-destructive/closed-world, so the bar is lower, and the description still adds real context: only *approved* cards are visible, results are newest-first, and paging is capped at 50 per page with a total count returned. It does not discuss rate limits or whether the catalog is scoped to the caller.

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 purpose and scope, with pagination and ordering folded in. No filler, nothing repeated from 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 described, and annotations cover the safety profile; the description still supplies paging cap, total count, and ordering. The only gap is guidance on interacting with the `search` and `fetch` siblings as a workflow.

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 six parameters including min/max limits; the description merely restates the filter names. The one genuine addition is clarifying that slug values are ids that `fetch` accepts, which ties the filter params to a downstream call, but it doesn't say what format slugs take.

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

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

States a specific verb+resource (list approved product cards) plus scope details: default ordering (newest first) and the four optional filters. It also hints at its relationship to fetch ("Each slug is an id that fetch accepts"), but it never contrasts itself with the sibling `search`, whose territory the `q` full-text parameter overlaps with.

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 filter list implies when this tool is appropriate (browsing the approved catalog by category/label/tag or free text), but there is no explicit when-to-use or when-not-to-use statement, and no mention of `search` or `list_categories` as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: result ordering (newest first), the shape of each row, and the response-driven pagination signal (next_page). It doesn't discuss scoping to the authenticated user or result limits beyond the schema's page size.

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 tight sentences, zero filler. Identity and payload come first, then the slug special case, then the pagination instruction — a sensible front-loaded order.

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?

Rich annotations, a full output schema, and 100% parameter coverage mean the description only needs to supply ordering, pagination-loop behavior, and single-vs-list mode — all present. Nothing an agent needs to call 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: slug switches the call to single-listing retrieval and overrides paging, and next_page is framed as the continuation token to feed back into page. It doesn't restate the 1–500 / 100-per-page bounds, which the schema already handles.

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

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

States a specific verb+resource — the caller's own listings on Neeed Directory — plus the ordering (newest first) and the returned fields (status, plan, badge, admin feedback, page to open). That is clearly distinct from sibling list/search tools, though the description never names a sibling to sharpen the contrast.

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 concrete routing rules within the tool: "Pass a slug to get one" for single-listing mode, and "When next_page is a number, call again with that page for older listings" for the pagination loop. It does not mention when to prefer siblings like update_listing or search, 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?

Annotations already cover the read-only/idempotent safety profile, and the description adds real behavioral context on top: a hard cap of 20 results, newest-first ordering, an 'approved-only' scope, and the short-query no-results behavior. Only the return field list overlaps with the output schema, which is minor redundancy rather than a 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?

Three short sentences, zero filler, with the scope and result cap front-loaded and the chaining hint placed immediately after the id explanation. Every sentence carries a distinct fact.

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

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

For a one-param read tool with annotations and an output schema, everything an agent needs is present: scope, ordering, result cap, minimum query length, and how the returned id is consumed. The return fields are already in the output schema, so no further explanation is required.

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 already documents the single query param and its 100-character truncation. The description still adds meaning beyond the schema by declaring a two-character minimum below which nothing is returned — a constraint an agent cannot see in the schema and would otherwise trip over.

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 ('Search approved products on Neeed Directory') plus ordering ('newest first'), which lets an agent infer this is the query-driven counterpart to list_products. It stops short of naming the sibling to prefer for browsing, so the differentiation is implied rather than explicit.

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 a clear downstream routing rule — 'pass it to fetch for a plain-text card' — which is genuinely actionable chaining guidance. It does not say when to prefer search over list_products/list_categories, so the alternative-selection side is left to inference.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false, openWorld=true), the description discloses the material consequences: nothing is published or charged until the claim link is opened and submitted, the automatic check either publishes or holds for review, and Premium returns a Stripe Checkout link paid in the browser. Those are exactly the behavioral facts an agent needs before invoking a write with real-world effects.

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

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

Two sentences, no filler, and the conditional auth mode is front-loaded so the branching is visible immediately. It is dense — the second sentence chains submission, auto-check, and Premium checkout in one breath — which costs a little readability but nothing is redundant.

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

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

For an eight-parameter, seven-required creation tool with an output schema already describing returns, the description covers both auth paths, the publish/review branch, the charge deferral, and the claim-link flow. It does not restate return values, which is correct given the output schema, and nothing an agent needs to call it 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 description coverage is 100%, so every one of the eight parameters is already documented in the schema, including the plan enum and the pricing_model meaning. The description only reinforces the plan parameter's deferred-charge semantics and adds no field-level guidance beyond that, so the baseline 3 applies.

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

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

The description names a specific verb (saves/submits) and resource (a product listing on Neeed Directory) and splits it into two clearly distinct modes: an unauthenticated draft with a claim link, and an authenticated submission. An agent can distinguish it from update_listing or upgrade_listing because the draft/claim-link flow and the publish-or-review check are unique to this tool.

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

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

It gives explicit preconditions for each path — 'Without sign-in' versus 'Signed in with permission to edit listings' — so an agent can tell which outcome to expect from the current auth state. It does not explicitly name sibling tools such as upgrade_listing or update_listing as alternatives for existing listings, which keeps it 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so safety and repeat-call behavior are covered. The description adds useful state-transition consequences about review status and the blocked rejected-listing case, though it does not clarify partial-update semantics or permissions.

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 editable fields and followed by the key review-state rules. No redundant or filler content.

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

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

Output schema exists, so return values need not be explained, and annotations cover the safety profile. The description covers ownership, editable fields, and review-state behavior, though it could say more about partial updates or whether slug itself is ever mutable.

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 all seven parameters are already documented in the schema, including slug as the identifier from my_listings. The description reinforces which fields are editable but adds little format or constraint detail beyond the schema.

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

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

States a specific verb and resource ('Edits one of your listings') and enumerates the editable fields, making it clearly distinct from sibling creation/upgrade tools such as submit_product and upgrade_listing. An agent can identify the operation 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?

Provides clear eligibility context: editing a non-live listing sends it back for review, live listings stay live, and rejected listings cannot be edited. It does not explicitly name alternatives for related tasks, but the conditions for valid use are concrete.

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 annotations already declaring destructiveHint, non-idempotent, and openWorld, the description still adds meaningful context: the effect is deferred ('nothing is charged until the maker opens the link and pays in the browser') and the output includes a price. It does not explain why the call is flagged destructive or that repeated calls produce separate sessions, but the key safety nuance is 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?

Two sentences, both earning their place: the first defines the return value and the upgrade effect, the second pre-empts the obvious concern about immediate billing.

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 returns a link rather than performing the charge, and the description makes that clear; an output schema exists so return details need no further explanation. Missing only failure modes such as an ineligible or already-Premium listing.

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

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

Only one parameter with 100% schema coverage, including the pattern and a pointer to my_listings as the source of the slug. The description adds the constraint that the slug must be a live Free listing, which is the one bit of 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?

States a specific verb, resource, and return value ('Returns a Stripe Checkout link that upgrades one of your live Free listings to Premium, with the price'). The scope ('live Free listings') helps separate it from update_listing, though no sibling is named explicitly.

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

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

The precondition 'live Free listings' implies when the tool applies, but the description never states what to do for an already-Premium listing or that update_listing is the tool for editing listing content. Usage is inferable rather than explicit.

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