NeedAnAI — AI tool catalogue

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds useful disclosure about what is returned (verdict, check timestamps, freshness label), but says nothing about failure cases — e.g. what happens for an unknown or never-scanned slug — or rate limits.

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, zero waste: the leading question frames the intent immediately and the second sentence enumerates the returned signals. 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?

An output schema exists, so the return-value enumeration is not strictly necessary, and the safety profile is in annotations. What is missing is the relationship to sibling tools — specifically how this differs from get_tool, which an agent would reasonably consider for the same 'tell me about this tool' intent.

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?

Single parameter with 100% schema description coverage, including a pattern and a reference URL format, so the schema carries the semantics. The description never mentions the slug or its expected form, so it adds nothing beyond the structured field — 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 action (check a tool's site liveness/status) and names the concrete payload: scanner verdict, verification timestamp, pricing timestamp, freshness label. It does not differentiate itself from siblings like get_tool, which could also plausibly return tool metadata, so an agent must infer the boundary.

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

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

Usage is only implied: an agent can infer this is for checking whether a listing is alive and how fresh its data is. There is no explicit 'use this when...' guidance, no exclusions, and no pointer to get_tool or compare_tools as alternatives for related 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?

The annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful scope by naming the comparison dimensions, but it does not disclose error behavior, slug resolution rules, or other operational details beyond what annotations and schema already provide.

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

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

The description is a single efficient sentence with the core purpose front-loaded. Every clause contributes either the comparison scope or the compared dimensions, with no wasted text.

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 annotations, schema, and output schema are rich, so the description does not need to explain safety or return values. It is complete enough to support correct invocation, though it omits explicit routing guidance versus sibling tools.

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 schema already defines the slugs array, minItems, maxItems, and slug pattern. The description repeats the 2–5 tool constraint but adds no additional meaning about slug format, handling of invalid slugs, or ordering.

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: 'Side-by-side comparison of 2–5 tools.' It also enumerates the compared dimensions, making the tool's output clear. It does not explicitly distinguish itself from sibling tools such as get_tool or find_alternatives, which keeps it at a 4 rather than 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?

The multi-tool comparison scope implies when the tool is useful, and the 2–5 tool constraint provides some operational context. However, it gives no explicit guidance on when to use this instead of get_tool, find_alternatives, or search_tools, and no exclusions or prerequisites are stated.

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

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

Annotations only declare the generic hint set (readOnly=false, destructive=false, idempotent=false, openWorld=false); the description adds real operational context the annotations cannot convey: a hard 2,000-row ceiling, a signed download URL with a 24-hour validity window, and an API-key requirement. It stops short of saying whether the export is generated synchronously or as a job, which matters for a bulk 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?

Three short sentences, front-loaded with what the tool does, then output artifact, then the auth constraint. No filler and nothing 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?

An output schema exists, so return shape need not be detailed, and the description still usefully explains the signed URL and its expiry. Auth is covered. The remaining gap is what happens at the 2,000-row boundary (truncation vs error) and whether the export is synchronous, which an agent would want before committing.

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% across 6 parameters, so the description must carry the load. It does explain format (JSON/CSV) and maxRows (the 2,000 cap) and 'filtered slice' hints that query/pricing/category are filters, but the 'task' parameter and the exact filter semantics of pricing/category are left entirely to the bare schema.

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

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

Specific verb ('Bulk export') plus resource ('a filtered slice of the catalogue') and output formats, which clearly separates it from search_tools/list_taxonomy style reads. It never names a sibling to contrast with, so differentiation is inferred rather than stated.

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

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

The word 'Bulk' plus the 2,000-row cap implies this is for large offline extracts rather than interactive lookup, so usage is inferable. However, there is no explicit 'use this instead of search_tools when...' guidance and no stated prerequisites beyond the API key.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral value beyond that: it discloses the ranking factors that determine ordering and that each result carries an explanatory rationale, which an agent cannot infer from annotations or schema. It stops short of covering the cap on results or behavior when no alternatives exist.

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

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

Two tight sentences with zero filler, and the substantive content (what is returned and how it is ranked) is front-loaded. The opening is a verbless fragment, which is slightly less crisp than it could be, but nothing is wasted.

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-value shape need not be explained, and the description still notes that entries carry rationales. For a three-parameter read tool with full annotation coverage, the only meaningful gaps are the undocumented limit parameter and undefined behavior when a slug has no alternatives.

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 67%: slug and samePricing are documented in the schema, and the description reinforces samePricing as an optional same-pricing-model filter. The limit parameter (1–25) has no description anywhere, and the description does not explain it or give a default, so the baseline 3 for high-but-incomplete coverage 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 names the resource precisely (alternatives to a given tool) and even specifies the ranking inputs — freshness, profile completeness, curation, inbound alternative listings — plus that each entry carries a rationale. That is far more specific than the title 'Find alternatives'. It does not explicitly distinguish itself from close siblings like compare_tools or recommend_for_task, which keeps it out of 5 territory.

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

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

There is no statement of when to use this versus compare_tools or recommend_for_task, which are the obvious adjacent tools for a similar intent. The only usage-adjacent information is 'Optionally restrict to the same pricing model,' which describes a parameter behavior rather than tool selection 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that the response is the 'full markdown body', which is useful return-content context, but it does not mention error behavior such as a missing 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?

The description is a single tight sentence with zero waste. The return content and lookup key are front-loaded, which is appropriate for a simple single-parameter read tool.

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 not be explained in detail, and annotations cover safety behavior. For a one-parameter read-only lookup, the description is nearly complete, though it could briefly note what happens if the slug is not found.

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 0% description coverage for the single slug parameter, so the description must compensate. It says only 'by slug' and does not explain slug format, origin, or constraints beyond what the parameter name and schema pattern already imply.

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 resource and return content: the full markdown body of one article, identified by slug. It implies a lookup operation and distinguishes itself from search_articles by emphasizing 'one article', though it 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?

The description implies usage by noting retrieval by slug, but gives no explicit guidance on when to use this tool versus search_articles or other siblings. There are no conditions, exclusions, or alternatives mentioned.

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, closed-world and non-destructive, so the safety profile is covered. The description adds the notable behavioral detail that the response includes pricing freshness, site status and a trailing provenance line, but says nothing about failure behavior for a bad slug or any limits.

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

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

Two short sentences, front-loaded with the core purpose, followed by a dense but purposeful inventory of payload fields. The enumeration is long but each item carries informational value; nothing is padded.

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

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

Read-only, single-parameter, and an output schema exists, so the description does not need to explain return values in depth. It covers scope, payload shape and the provenance trailer; only edge behavior (invalid/missing slug, whether alternatives are always five) is unaddressed.

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?

Single parameter with 100% schema description coverage, including the URL pattern that defines the slug format. The description only restates 'by slug', adding no constraints beyond the schema, 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?

Specific verb ('Full profile') and resource ('one tool by slug'), with the returned payload enumerated. It is clearly a single-tool detail fetch, which implicitly separates it from search_tools, compare_tools and find_alternatives, but 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?

Usage is only implied: an agent infers it should call this when it already has a slug and needs full detail. There is no statement of when to prefer it over compare_tools or find_alternatives, and no note about what happens for an unknown slug.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only one behavioral detail beyond that — that counts are 'live' — and says nothing about caching, ordering, or how counts are computed. With annotations carrying the burden, a 3 is appropriate.

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: the first states what is returned, the second states what to do with it. No filler, and the payload description is front-loaded ahead of the usage pointer.

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 return shape needn't be explained, and the required enum parameter is trivial. Purpose, content, and downstream use are all covered; only the practical meaning of 'categories' versus 'tasks' for this registry is left implicit, which is a minor gap for a one-parameter read 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 0%, so the description must carry the parameter meaning — and it does by naming both concepts ('category or task') matching the required 'kind' enum. The distinction between a category and a task is left to the enum values themselves, but for a single self-describing enum parameter this is adequate.

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 exact resource returned ('All category or task slugs with names and live tool counts'), which is a specific noun-plus-contents statement rather than a restatement of the title. It implicitly separates itself from sibling tools like get_tool and search_tools by describing a taxonomy enumeration, though it never explicitly contrasts with them.

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

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

It gives actionable downstream context: 'Use the slugs as filters for search_tools and recommend_for_task,' which tells the agent this is a discovery/enumeration step feeding two named siblings. It lacks an explicit when-not or a statement like 'call this first if you don't know the slugs,' so usage is strongly implied rather than fully spelled out.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without prose. The description adds one genuine piece of context beyond that — results are scoped to the current API key and limited to 'active' watches — but does not explain what 'active' excludes (expired, paused, triggered), which is the main behavioral question here.

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

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

It is certainly short with no padding, but it is a sentence fragment rather than a well-formed, front-loaded description, and the brevity comes at the cost of under-specification. There is no wasted text, yet the single fragment is doing too little work.

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 not be described, and with zero parameters the schema burden is nil. Still, for a list tool whose only real ambiguity is what 'active' means and how results relate to watch_tool/unwatch_tool, the description leaves an agent guessing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description neither helps nor hurts parameter understanding.

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 fragment 'Active watches on this API key' nominally identifies the resource (watches) and scope (API key), and the title supplies the missing verb 'List'. However, the description itself never states the verb, and it does not distinguish this list operation from siblings like watch_tool or unwatch_tool that operate on the same resource.

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

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

There is no guidance on when to call this versus alternatives such as unwatch_tool, nor any prerequisite or context statement. The only implicit usage signal is the word 'Active', which hints at filtering but is never explained or contrasted with any sibling.

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 establish read-only, idempotent, non-destructive, closed-world semantics, so the bar is lower. The description still adds real value by disclosing the resolution strategy (slug lookup before free-text fallback) and that each recommendation carries an explicit rationale, which shapes how an agent should read the response.

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

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

Two tight sentences with the core behavior front-loaded and the resolution strategy following as supporting detail. No filler, nothing repeated from the name or title.

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 (recommendations plus rationales) don't need spelling out. What's missing is the semantics of 'limit' and the 'budget' enum and any note on behavior when no match is found — modest gaps for an otherwise simple read-only 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%: 'task' is documented in the schema and echoed in the description, but 'limit' (1-10) is never mentioned at all, and 'budget' is only labeled 'optional' without explaining whether the enum filters results or just ranks them. With low coverage the description needed to compensate and largely did not.

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-plus-resource ('returns the best-fitting tools' for a given job to be done) and gives two concrete example tasks. It's clearly distinct from siblings like search_tools or compare_tools, though it never names them explicitly to sharpen the distinction.

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 implies the usage context (I have a job to be done, optionally constrained by budget) and hints that slug input is preferred via 'resolves known task slugs first, then falls back to free-text search.' But it never states when to pick this over search_tools or find_alternatives, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered structurally. The description adds useful scope context (660+ articles, editorial rather than tool data), but says nothing about result ordering, pagination, or truncation behavior.

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 tightly packed sentence with the resource scope front-loaded and zero filler. Every clause adds information an agent can use.

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 shape needs no explanation, and the corpus scope is clear. However, for a search tool the omission of the limit parameter and any notion of result ordering or pagination leaves a practical gap.

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

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

Schema description coverage is 0%, so the description carries the full burden. It conveys that query is keyword-based and category is optional, but never mentions the limit parameter or its 25-result cap, and gives no format hints for category values.

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 (search) and resource (editorial articles), and enumerates the content types covered, which tells an agent what corpus it's hitting. It doesn't explicitly contrast itself with get_article (single-article fetch) or search_tools (different corpus), so sibling differentiation is only implied.

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 phrase 'by keywords and optional category' implies the invocation mode, but there is no explicit statement of when to prefer this over get_article or search_tools, nor any exclusions. Usage is inferable rather than instructed.

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 carry readOnly/idempotent/non-destructive/openWorld=false, so the bar is lower, and the description still adds real signal: ranked results, facet counts, freshness provenance ('when the site was last confirmed alive'), and a separate labelled sponsored block that tells the agent ads are isolable from organic hits. It omits the 25-per-page / 400-page caps, but those live in 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?

Two sentences, zero filler, with the core capability front-loaded and the prerequisite pointer placed last where it is needed. Every clause carries information.

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

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

Output schema exists so return shape needn't be spelled out, yet the description still flags the sponsored-block separation an agent would otherwise miss. With full annotation coverage, 86% schema coverage and no required parameters, nothing an agent needs to call this correctly is absent.

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 86%, so the schema already documents page, perPage, query, pricing, category and task. The description adds little syntax detail beyond naming the search axes, though the list_taxonomy pointer usefully reinforces that category/task expect slugs rather than free text. Baseline 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?

Specific verb + resource ('Search the NeedAnAI catalogue of 15,000+ AI tools') with the searchable axes (free text, pricing model, category, task) and catalogue scale stated up front. An agent knows immediately this is the free-text/browse entry point rather than a lookup by id (get_tool) or a comparison (compare_tools).

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 to list_taxonomy for valid category and task slugs, which is the key prerequisite for two of the seven parameters. It does not, however, say when to prefer recommend_for_task or search_articles over this tool, so the sibling routing is only partially covered.

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 write/non-destructive/non-idempotent profile, and the description adds two pieces of genuinely non-derived information: the auth requirement and the dedupe behavior (an existing listing is returned if the website is already listed). It does not cover moderation/review outcomes or what happens on validation rejection, so it earns a 4 rather than 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?

Three short sentences, front-loaded with the core action, then the dedupe edge case, then the auth prerequisite. Nothing is padded or 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?

An output schema exists, so return values need no explanation, and the annotations plus description cover the mutation profile adequately. The clear gap is parameter documentation: an agent knows what the tool does but not what fields it must supply or what the pricingType enum values mean in 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?

Schema description coverage is 0% across 4 parameters, so the description carries the full burden and largely fails it — only the implicit link between "its website" and the url field is hinted at. There is no mention of name, description, or the 6-value pricingType enum, nor of length 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?

"Suggest a tool for the catalogue" states a specific action (submitting/suggesting) and resource (a tool listing in the catalogue), which is clearly distinguishable from read-side siblings like get_tool, search_tools, and compare_tools. It stops short of explicitly naming a contrasting sibling, so a 4 rather than 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?

The description implies when this applies (you have a tool to propose) and adds a real prerequisite — "Requires an API key" — but gives no explicit exclusions or comparisons against alternatives such as get_tool for checking whether something already exists. The duplicate-handling sentence is behavioral, not guidance on tool selection.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds no further behavioral context such as permissions, reversibility, or side effects beyond what the annotations provide.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately sized for a simple one-parameter tool.

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, has an output schema, and annotations cover the destructive/idempotent behavior. However, the description omits usage guidance and parameter context, leaving a clear gap for an agent selecting the 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 0%, so the schema does not document the id parameter beyond its UUID format. The description says "by id" but does not explain how to obtain the watch id or add meaningful semantics beyond the 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?

States a specific verb and resource: "Stop a watch by id." The action is clear, but it does not explicitly differentiate this from sibling tools such as watch_tool or list_watches.

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 no explicit guidance on when to use this tool versus watch_tool or list_watches. Usage is only implied by the phrase "Stop a watch by id."

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 declare non-readonly, non-destructive, idempotent, closed-world, so safety is covered; the description then adds genuinely new behavior: a 30-minute polling cadence, delivery via https webhook or email, and an explicit API-key requirement with a URL to obtain one. That is meaningful context beyond structured fields. It stops short of describing what happens on delivery failure or how duplicate subscriptions behave, which would have pushed it higher.

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, each earning its place: what it does and cadence first, delivery channel second, prerequisite/auth last. No filler and the most decision-relevant facts are 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 create-subscription tool with an output schema (so return values need no explanation) and full annotation coverage, the description supplies the key operational facts an agent needs: cadence, delivery mechanism, and auth requirement. Only edge-case behavior such as re-subscribing to an already-watched slug is unaddressed, though idempotentHint implies it is safe.

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 67% and the schema already documents slug format, target length limits, and the channel enum, so the burden on the description is modest. The description reinforces that target must be an https webhook or email and ties channel to those two delivery modes, but adds no format or validation 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 ("Subscribe to") and a specific resource ("status and pricing changes for a tool"), so an agent knows exactly what the call creates. It does not name the sibling tools (unwatch_tool, list_watches) that represent the opposite or listing operation, so sibling differentiation is left to inference rather than stated.

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

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

Usage is implied by the purpose: use it when you want ongoing monitoring of a tool's status/pricing. However, there is no explicit when-to-use vs when-not guidance, and the relevant alternatives (unwatch_tool to remove a subscription, list_watches to see existing ones) are never mentioned.

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