catalog

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

Description adds value beyond annotations by detailing return content: date, cause of shutdown, and live alternatives. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. No contradiction; description enriches behavioral understanding.

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: one defining output, one providing usage context. Front-loaded with action and return type. Every sentence is essential and no redundant 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?

Given the low complexity (1 param, no output schema, rich annotations), the description covers the main use case and output structure. However, it doesn't mention behavior for missing tools or error conditions, which is a minor 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 100% for the single parameter 'tool', and the description reinforces its purpose. With full schema coverage, baseline is 3. Description doesn't add new semantics beyond the schema's explanation of 'tool name or directory slug'.

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

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

Description clearly states the tool checks if an AI tool is active, with specific verb 'Check whether' and resource 'tool status'. It distinguishes from siblings like get_tool or search_tools by focusing on liveness and recommending use before suggesting a 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?

Explicitly says 'Use this before recommending a tool to avoid suggesting one that no longer exists.' This provides clear context, though it doesn't explicitly mention when not to use it. Still, it gives actionable 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by specifying that the head-to-head verdict is conditional ('when one exists') and detailing the return fields (pricing, rating, etc.), which provides behavioral context beyond the annotations.

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

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

The description consists of two concise sentences. The first sets the high-level action; the second itemizes the return data. Every word is necessary, and there is no redundancy or filler.

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

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

For a tool with 2 required params, no output schema, and no enums, the description adequately explains what is returned (profiles and conditional verdict). It does not detail output format or pagination, but those are unlikely needed for a comparison tool. The sibling context is provided.

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 slugA and slugB described as 'Directory slug of the first/second tool.' The description redundantly mentions 'directory slugs' but adds no new meaning or constraints beyond the schema. 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?

The description clearly states the tool's verb ('Compare') and specific resource ('two AI tools side by side by their directory slugs'). It outlines what is returned (profile fields and head-to-head verdict), and the sibling tools list shows alternatives like get_tool (single) and list_tools, so this tool is distinctly for pairwise comparison.

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 tool is for comparing two tools by slugs, which differentiates it from siblings like get_tool (single) or search_tools. However, it does not explicitly mention when not to use it or suggest alternatives, leaving some inference to the agent.

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 indicate the tool is read-only, idempotent, and non-destructive. The description adds value by revealing that alternatives are 'curated' (not algorithmically generated) and that there is special handling for defunct tools. This provides behavioral nuance beyond what annotations alone convey. It does not contradict any 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 exactly two sentences: the first states the core functionality, the second adds a special case and a usage hint. Every word earns its place; there is no fluff. It is front-loaded and easy to scan. This is a model of concise, effective description writing.

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 required param, no output schema), the description adequately informs the agent of the tool's purpose and behavior. However, it does not specify the format of the returned alternatives (e.g., list of names, objects with descriptions). Since there is no output schema, a bit more detail about the return value would improve completeness. Still, it covers the essential usage context well.

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 description coverage and only one parameter ('slug'), the schema already fully documents the parameter. The description does not add any additional meaning or constraints beyond what the schema provides. Per the guidelines, baseline 3 is appropriate when schema coverage is high and description adds no extra param context.

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

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

The description clearly states the action ('find curated alternatives') and the resource ('AI tool by its directory slug'). It handles a special case (shut-down tools returning live replacements). It distinguishes from sibling tools like 'get_tool' (which returns a single tool's details) or 'compare_tools' (which compares multiple tools). The verb and resource are specific and unambiguous.

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

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

The description explicitly states the tool is for 'what should I use instead of X' questions, providing clear use context. It also covers the edge case of shut-down tools. While it does not explicitly list when not to use it, the purpose is narrow enough that the agent can infer appropriate usage. A clearer exclusion (e.g., 'not for general tool search') would push it to 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 readOnlyHint, idempotentHint, and destructiveHint false, so the description adds value by specifying the returned fields and scope (full profile). No contradictions.

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, well-structured sentence listing the exact return fields. No extraneous information; every word earns its place.

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

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

Given the single parameter, no output schema, and annotations present, the description adequately conveys the tool's purpose and output without missing critical 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% for the single parameter 'slug', and the schema already includes an example. The description mentions 'by its directory slug' but adds no new semantic 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?

The description clearly states the tool retrieves the full profile of one AI tool by slug, listing specific fields (description, pricing, features, verdict, rating, verification date, status, URL). This differentiates it from sibling tools like search_tools (search/list) or 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?

The description implies usage when you have a directory slug, such as from search_tools. It does not explicitly state when not to use or name alternatives, but the context and sibling names provide clear 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 convey safety (readOnlyHint). Description adds behavioral context: 'top-rated active' implies ranking and activity filters. No contradictions.

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 compact sentences: first states purpose, second provides usage examples. No wasted words; front-loaded with essential info.

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 full schema coverage, good annotations, and no output schema, the description is nearly complete. It could mention result ordering or pagination, but adequately covers core behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by linking parameters to examples (e.g., 'sales' for role, 'productivity' for category) and mentioning filtering behavior, enhancing meaning beyond 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 clearly specifies the action (list), resource (top-rated active AI tools), and scope (by category or job role, optionally filtered by pricing). It effectively distinguishes from siblings like search_tools and get_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?

Provides concrete example queries ('what are the best AI tools for sales', 'free tools in <category>'), indicating when to use. Lacks explicit 'when not to use' or alternatives, but the context is sufficient.

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 convey safety and idempotency. Description adds return format details (slug, description, pricing, rating), enhancing transparency beyond 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?

Two concise sentences: first explains functionality, second provides usage guidance. No superfluous 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?

Complete given low complexity: covers return fields and chaining. No output schema needed as return is sufficiently described.

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 3. Description does not add new meaning beyond what schema already provides for both parameters.

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?

Clearly states the action (search), resource (AI Tool Directory catalog), and method (hybrid semantic search). Distinct from siblings like get_tool or list_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 advises to use this for discovery and then get_tool for full detail. Could be more precise about when not to use, but adequate.

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