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

Annotations declare readOnlyHint=true; description complements this by detailing the four analytical dimensions returned (Freshness, Cohesion, Modernity, Per-dependency status) and explicitly instructing proactive invocation behavior without user prompting.

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?

Well-structured with clear section headers (Returns, Use this when, Args) and front-loaded purpose. The proactive instruction paragraph and detailed return value bullets are necessary for agent behavior calibration, though the total length approaches the upper bound of conciseness.

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?

Comprehensive given the output schema exists: covers parameter semantics, return value summary, and usage contexts. Minor gap: does not explicitly mention limitations (e.g., only npm/pip ecosystems supported) or error handling scenarios.

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?

Critical compensation for 0% schema description coverage: explicitly defines 'manifest' as full text content of specific files and 'file_type' with valid values and default behavior ('auto-detected if omitted'), providing essential semantic context missing from the structured schema.

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

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

The description opens with a specific verb ('Analyze') + resource ('project's dependencies') + concrete output ('health score 0-100'), immediately distinguishing it from siblings like scan_project or check_health by focusing specifically on manifest file analysis.

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

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

Provides explicit 'Use this when:' criteria with four specific scenarios including proactive usage ('whenever you see a package.json'), starting new projects, reviewing existing stacks, and pre-upgrade audits. Clearly defines trigger conditions vs. 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 declare readOnlyHint=true confirming safe read operation. Description adds valuable behavioral context distinguishing this from relevance-based search, and explains pagination behavior in the Args section. Does not mention rate limits or caching, but covers primary behavioral traits.

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?

Well-structured with clear paragraph breaks: purpose, usage guidelines, sibling differentiation, then parameter details. Every sentence serves a distinct function; no redundancy. Front-loaded with the core action.

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 2-parameter read-only tool with existing output schema, the description is comprehensive. It handles sibling differentiation, usage contexts, and parameter documentation that the schema lacks. No critical gaps remain.

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

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

Schema coverage is 0% (properties lack descriptions), but description fully compensates via Args section documenting limit ('default 10, max 50') and offset ('Pagination offset... Use offset=10 to see the next page'), providing semantics, defaults, and usage guidance absent from 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?

Opens with specific verb 'Browse' + resource 'recently added developer tools on IndieStack'. Explicitly distinguishes from sibling tool find_tools() by clarifying this returns 'newest arrivals across all categories, not ranked by relevance'.

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

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

Provides explicit when-to-use scenarios ('when the user asks what's new, what's trending, or wants to explore... without a specific need') and explicit fallback condition ('when find_tools() returns no results'). Names the alternative tool directly.

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=true. Description adds valuable behavioral context: return values ('recommended tools, matching curated stacks, estimated tokens saved'), catalog scope ('6,500+'), and efficiency metrics ('50,000-token... into 2,000-token'). Does not contradict read-only nature.

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?

Well-structured with value proposition front-loaded ('Assemble...'), followed by mechanics, usage conditions, and efficiency justification. The Args block is clearly demarcated. Zero redundant sentences; every line advances understanding.

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 2-parameter tool with existing output schema, description is complete. Covers input format, output summary, usage triggers, performance characteristics, and parameter semantics without needing to duplicate structured output schema 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 0%, requiring description to carry full burden. Args section fully compensates: 'needs' includes format (comma-separated) with concrete example ('auth,payments...'), and 'budget' specifies units (USD), scope (per tool), and semantics of default value (0 = no limit).

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 uses specific verb 'Assemble' with clear resource 'complete tool stack' and distinguishes from siblings by emphasizing 'proven components instead of generating from scratch' and referencing the '6,500+ IndieStack catalog.'

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

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

Provides explicit when-to-use scenarios ('starting a new project, planning architecture, or asking "what should I use for X"'). Lacks explicit when-not-to-use guidance or named sibling alternatives (e.g., vs. find_tools for single tools).

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=true, confirming this is a safe read operation. The description adds valuable behavioral context beyond annotations: it discloses the output structure ('compatibility matrix' with three specific states: verified, unknown, conflict), input constraints ('2-8 tool slugs'), and sequencing recommendations (calling check_health after). It could improve by mentioning rate limits or caching 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?

Well-structured with purpose upfront, followed by usage context, specific constraints, workflow guidance, and finally parameter details. No redundant sentences; the 'Args' section efficiently documents the single parameter without unnecessary verbosity.

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

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

Given the presence of an output schema, the description appropriately summarizes return values (the three matrix categories) without duplicating schema details. It covers the single parameter thoroughly despite sparse schema documentation. Minor gap: does not mention error handling for invalid slugs or out-of-range tool counts.

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 0% schema description coverage, the description fully compensates by providing the parameter format ('Comma-separated tool slugs'), a concrete example ('next-auth,prisma,stripe'), and quantity constraints ('2-8'). It does not explicitly describe the parameter as required, though this is visible in the schema's required array.

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 opens with a specific verb ('Check') and clear resource ('whether a set of tools are compatible'). It distinguishes from siblings by explicitly directing users to 'Call check_health() afterward for maintenance status,' clarifying this tool handles compatibility matrices while check_health handles maintenance status.

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

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

Explicitly states when to use ('validate a stack before recommending it', 'Ideal for always-on agents auditing dependency trees') and provides workflow integration ('Call check_health() afterward'). Also includes operational constraints ('Pass 2-8 tool slugs') that define valid usage boundaries.

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 readOnlyHint=true. The description adds valuable behavioral context by detailing what data is returned (maintenance status, stars, issues) and explaining the tool's logic (flags stale/archived tools, suggests alternatives). No contradiction with 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?

Excellently structured with clear sections: purpose, return values/behavior, usage scenarios, and arguments. Information is front-loaded and every sentence serves a specific function. The bullet points for usage scenarios are efficient and scannable.

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 the tool's moderate complexity and rich ecosystem context. It references the output schema implicitly by summarizing returned fields, and explicitly links to sibling tool find_tools() to complete the usage workflow. No gaps remain for an agent to invoke this tool 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?

With 0% schema description coverage, the description fully compensates by documenting the 'slugs' parameter format (comma-separated), providing concrete examples ('hanko,plausible,polar'), and specifying provenance ('Get slugs from find_tools() search results'), which is critical for successful invocation.

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

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

The description opens with a specific verb ('Check') and resource ('maintenance health of indie tools'), distinguishing it from sibling tools like find_tools (discovery) or compare_tools (comparison). It further clarifies scope by listing specific outputs (last commit date, GitHub stars, open issues) and actions (flags stale tools, suggests alternatives).

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

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

Provides an explicit 'Use this when:' section with four specific scenarios (reviewing tech stack, pre-commitment evaluation, dependency checks, auditing). This offers clear positive guidance, though it stops short of explicitly naming alternative tools for different use cases (e.g., 'use analyze_dependencies for code-level analysis 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 declare readOnlyHint=true. Description adds valuable behavioral context beyond annotations: specifies output format ('crisp side-by-side table'), lists compared attributes (price, source type, upvotes, ratings, ejectable flag), and notes it provides a recommendation. Could improve by mentioning if results are cached or real-time.

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?

Well-structured and front-loaded: starts with purpose, urgency ('IMMEDIATELY'), value proposition ('Cuts decision time'), data coverage, then params. Every sentence earns its place. Minor deduction for informal 'Args:' section embedding param docs, though necessary given empty schema descriptions.

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?

Appropriately complete given output schema exists. Description wisely focuses on comparison semantics and trigger conditions rather than return structure. Lists all compared fields comprehensively. Could mention return type (table vs JSON) but sufficient for agent selection.

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 has 0% description coverage (only titles 'Slug A/B'). Description fully compensates by specifying these are 'URL slugs' and providing concrete examples ('plausible-analytics', 'simple-analytics'). Clarifies ordinal relationship ('First tool', 'Second tool'). Slight deduction for not mentioning format constraints (kebab-case, etc.).

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?

Clear specific verb ('Compare') + resource ('IndieStack tools') + scope ('side by side'). Explicitly distinguishes from sibling get_tool_details by contrasting with 'reading two separate tool details' and establishes relationship with find_tools as the trigger.

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?

Excellent explicit guidance: 'Call this IMMEDIATELY when find_tools() returns 2+ plausible options.' Defines precise trigger condition (user hasn't committed) and implicit alternative workflow (don't use for single tools). Mentions sibling find_tools by name as prerequisite.

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?

Correctly aligns with readOnlyHint: false by noting the write scope requirement. Adds valuable context about side effects ('improves compatibility recommendations for all users') and setup requirements (dashboard URL) that annotations do not cover.

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?

Efficiently structured with the action front-loaded, followed by usage context, auth requirements, and parameter definitions. The Args section is clearly delineated. No redundant sentences, though the URL could be considered optional for an agent.

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?

Appropriate for the tool's complexity. Since an output schema exists, the description correctly omits return value details. Covers essential operational context (auth, usage trigger) that structured fields lack, though could mention error handling or idempotency given the write operation.

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 0% schema description coverage, the description compensates by documenting all three parameters in the Args section. However, the definitions are minimal ('First tool slug', 'Optional context') and lack format details or semantic richness that would help an agent populate them correctly.

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 core action ('Report that you successfully integrated two tools') and resource (integration). It contextualizes this as an IndieStack-specific action, but does not explicitly differentiate from similar sibling tools like 'report_compatibility' or 'report_outcome'.

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

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

Provides explicit when-to-use guidance ('Call this when you help a user connect two IndieStack tools') and prerequisites ('Requires an API key with write scope'). Lacks explicit 'when not to use' or named alternatives to distinguish from other reporting tools.

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?

Correctly aligns with readOnlyHint=true by describing a calculation/analysis operation. Adds valuable context beyond annotations by disclosing the output format (3-year TCO, break-even point, verdict) and behavioral bias ('financial case almost always favors an existing tool'), though it omits rate limits or data freshness concerns.

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?

Well-structured with clear paragraph breaks separating purpose, usage triggers, and Args documentation. Front-loaded with the core calculation purpose. Length is justified given the need to inline all parameter documentation, though the Args block adds density.

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?

Appropriately leverages the existence of an output schema by summarizing key return values (TCO, break-even) rather than exhaustively documenting them. Fully compensates for the sparse input schema (0% coverage). Could briefly mention assumptions or data sources for the financial model.

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 0% schema description coverage (only titles provided), the description fully compensates by documenting all three parameters: 'slug' includes domain context ('IndieStack tool slug') and example ('plausible-analytics'), while numeric parameters include units (USD) and defaults (20, $100) not present in the schema.

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

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

The description opens with a specific verb+resource combination ('Calculate whether to build...') and distinguishes itself from sibling recommendation tools (recommend, compare_tools) by specifying it performs financial TCO analysis and returns a 'BUY or BUILD verdict' rather than general tool suggestions.

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

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

Provides explicit temporal guidance ('Call this BEFORE recommending...'), lists specific infrastructure categories (auth, payments, analytics, email), and includes exact user trigger phrases ('I'll just build it myself', 'how hard can it be') that should invoke this tool versus general 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 only declare readOnlyHint=true. Description adds valuable return structure context ('grouped by category, with integration report counts, verified stacks... and conflict warnings') and data provenance ('agent-verified integrations'). Does not cover error cases or pagination, but output schema exists to cover return details.

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?

Well-structured with front-loaded purpose statement, followed by invocation timing, return value summary, workflow pattern, and parameter documentation. No redundant sentences; every line advances understanding of tool usage or semantics.

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?

Comprehensive coverage given 3 parameters with no schema descriptions and existing output schema. Description addresses all parameters, provides workflow context, and explains return value categories. Sufficient for agent to invoke correctly without consulting external documentation.

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 has 0% description coverage. Description fully compensates via Args section: slug includes example ('supabase') and source ('find_tools() results'), category includes purpose ('filter companions') and example ('authentication'), min_success_count explains semantics ('integration reports') and default.

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 'Find' with clear resource 'tools' and scope 'known to work well with a specific tool'. Effectively distinguishes from siblings like find_tools (general search) and check_compatibility (pairwise checking) by focusing on companion discovery post-selection.

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 workflow guidance: 'Call this after selecting a tool', 'Use this for stack assembly: pick your first tool, then find_compatible() to build around it'. Also specifies input source dependency: 'Get slugs from find_tools() results'. Contrasts with guessing 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 declare readOnlyHint=true, confirming safe search behavior. The description adds valuable behavioral context beyond annotations: dataset characteristics (6,500+ IndieStack tools), filtering constraints ('Code tools only' for language/stars parameters), and critical behavioral notes ('Soft filter' for min_success_rate). Could improve by mentioning pagination limits or rate limiting.

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?

Length is substantial but justified by 15 undocumented parameters requiring manual documentation. Structure is well-organized: purpose → usage guidelines → value proposition → parameter reference. Every sentence earns its place; the prose paragraphs front-load critical workflow logic before the necessary parameter enumeration. Minor verbosity in value-proposition paragraph ('maintained by domain experts instead of nobody') prevents a 5.

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 15 parameters, 0% schema coverage, and presence of output schema, the description achieves completeness. It integrates with the sibling ecosystem (23 tools) by explicitly referencing list_categories() and contrasting with code generation workflows. The parameter documentation is exhaustive, and the output schema handles return value descriptions, making this sufficient for correct invocation.

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?

Despite 0% schema description coverage (schema only has titles), the description compensates with a comprehensive 'Args:' section documenting all 15 parameters with examples, valid values, and format specifications (e.g., 'comma-separated tags', '0-100' range, specific enum values). It even references sibling tool list_categories() for valid category slugs, adding workflow 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 opens with the specific verb 'Search' and clear resource scope '6,500+ developer tools'. It effectively distinguishes from siblings via explicit workflow guidance: 'Query this tool BEFORE generating boilerplate' positions it against build_stack/generation tools, while referencing list_categories() for valid slugs clarifies its relationship to discovery siblings.

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

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

Provides explicit when-to-use guidance: 'Query this tool BEFORE generating boilerplate for common infrastructure' and enumerates specific domains (auth, payments, analytics, etc.). It also establishes clear alternatives (generating code from scratch) and quantifies the cost of not using it (30,000-80,000 tokens), creating strong decision boundaries.

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 readOnlyHint annotation, the description adds valuable behavioral context: it explains that results are 'zero-result queries ranked by search volume,' clarifies the ranking methodology (search volume), and interprets the business meaning ('unmet demand'). It does not mention rate limits or pagination, but covers the core return behavior well.

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?

Efficiently structured with a clear progression: concept definition → return format → business interpretation → use cases → parameter documentation. No wasted words. The 'Args:' section is slightly informal but clear. Each sentence earns its place by adding distinct 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 tool has an output schema and simple integer parameters, the description is appropriately complete. It explains the domain-specific concept of 'market gaps' sufficiently for an agent to understand what is being returned, without needing to duplicate the output schema structure.

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 0% schema description coverage (only titles provided), the description fully compensates by documenting both parameters in the Args section: 'days' is defined as 'Look back period' with constraints (default 30, max 90), and 'limit' is defined as 'Number of gaps to return' with constraints (default 10, max 50).

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 immediately defines 'market gaps' as 'things developers and AI agents search for but can't find' and clarifies these are 'zero-result queries ranked by search volume.' It distinguishes from sibling tools like find_tools by emphasizing unmet demand for tools that 'don't exist yet' versus finding existing ones.

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?

Clearly states when to use: 'for tool makers deciding what to build next' and 'for agents understanding what categories have coverage gaps.' However, it does not explicitly mention when NOT to use it (e.g., 'do not use when looking for existing tools') or name specific sibling 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 only declare readOnlyHint=true. The description adds critical behavioral context: data provenance ('mined from real package.json / requirements.txt diffs across thousands of GitHub repos'), methodology ('verified package diff analysis'), and return structure ('momentum signal, adoption sources, departure destinations').

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?

Excellent structure with front-loaded value proposition, followed by methodology, bulleted usage scenarios, return value summary, and parameter details. No wasted words; every sentence provides actionable context.

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

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

For a single-parameter tool with existing output schema, the description is comprehensive: covers data source, usage contexts, return values, and parameter semantics. No gaps remain for the agent to use the tool effectively.

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?

Despite 0% schema description coverage, the Args section fully compensates with concrete examples ('jest', 'express'), format constraints ('npm/pip package name, not IndieStack slug'), and explicit lookup instructions via get_tool_details() 'SDK Packages' field.

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

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

The description opens with specific verb+resource ('Query real migration data from GitHub repos') and clearly distinguishes from siblings by emphasizing 'ground truth, not marketing' and migration-specific analysis (FROM/TO package flows) versus general tool info or recommendations.

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?

Includes explicit 'Use this when:' section with four specific scenarios (deciding between tools, validating migrations, checking momentum, industry direction). Also cross-references sibling tool get_tool_details() for package name resolution, providing clear workflow 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?

Beyond the readOnlyHint annotation, the description adds valuable privacy context ('never raw queries, never conversation context'), external profile management options ('View or delete your profile at...'), and operational dependencies ('after a few searches').

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?

Well-structured with clear paragraph separation between purpose, privacy policy, usage guidelines, and parameters. Every sentence adds unique value, though the privacy and profile management details make it slightly longer than minimal.

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

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

Given the presence of an output schema (relieving the description of return value documentation), the description adequately covers the tool's purpose, privacy implications, usage timing, and parameter semantics for a 2-parameter read-only operation.

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 0% schema description coverage, the description fully compensates by documenting both parameters in the Args section: 'category' includes specific examples ('analytics', 'auth', 'payments') and omission behavior, while 'limit' specifies the valid range (1-10) and default 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?

The description opens with a specific verb ('Get') + resource ('recommendations') + mechanism ('based on your search history'), clearly distinguishing it from the sibling tool 'recommend' by emphasizing the personalized, history-driven nature of the results.

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

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

Provides explicit temporal guidance ('Use this after a few searches') and concrete user query triggers ('when the user asks "what else is out there"'), giving the agent clear signals for when to invoke the tool.

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

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

While annotations declare readOnlyHint=true, the description adds valuable behavioral context about what gets returned: 'install commands, environment variables, SDK packages, migration signals, and trust tier.' It also clarifies the output nature as 'actionable integration documentation the user can implement immediately,' adding implementation context beyond the annotation.

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?

Information-dense and well-structured with clear front-loading of the core purpose. The enumerated list of data types (install commands, SDK packages, etc.), while lengthy, is necessary to convey scope. The Args section is efficiently delineated. No redundant or tautological statements.

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

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

Given the presence of an output schema and only a single parameter, the description provides excellent contextual completeness by mentioning the catalog scope (6,500+ tools), the actionable nature of outputs, and the prerequisite workflow. It successfully bridges the gap left by minimal annotations and zero schema coverage.

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 0% schema description coverage (slug parameter lacks description), the description fully compensates by defining the parameter as 'The tool's URL slug,' providing a concrete example ('plausible-analytics'), and specifying provenance ('Get slugs from find_tools() results'), giving the agent complete semantic 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 description uses specific verbs ('Get integration code, pricing, API specs...') and identifies the exact resource ('6,500+ IndieStack catalog'). It clearly distinguishes from sibling tools by establishing the workflow sequence: 'Call this after find_tools()', explicitly naming the prerequisite 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 explicit temporal guidance ('Call this after find_tools()') that establishes when to invoke the tool in the workflow sequence. It implies the prerequisite (having a slug from find_tools) and orients the agent to the two-step discovery-then-detail pattern, effectively distinguishing it from the sibling find_tools.

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 establish readOnlyHint=true, and the description adds valuable behavioral context: it specifies the return contains 'slugs you can pass directly to find_tools(category=...)' and quantifies the scope ('25 categories'). It does not contradict the readOnly annotation.

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 sentences with zero waste. The first sentence establishes purpose, the second and third provide usage guidelines with specific sibling references, and the fourth adds contextual scope (25 categories). Every sentence earns its place.

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

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

For a zero-parameter read-only tool with an output schema, the description is complete. It explains what the output contains (slugs, tool counts), quantifies the dataset (25 categories), and describes the primary integration point (find_tools). No gaps remain given the tool's simplicity.

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

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

The tool has zero parameters, which per the rules establishes a baseline of 4. The description implicitly confirms no filtering is needed by emphasizing it lists 'all' categories, aligning with the empty input schema.

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

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

The description opens with a specific verb ('List') and resource ('IndieStack categories') plus a key attribute ('with tool counts'). It clearly distinguishes from sibling tools like list_tags and list_stacks by focusing specifically on categories and their relationship to find_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 states two clear when-to-use scenarios: 'when you're unsure what category slug to pass to find_tools()' and 'when you want to survey the full landscape.' It also identifies the specific sibling tool (find_tools) that consumes this tool's output, creating a clear workflow.

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=true, confirming safe read access. The description adds valuable behavioral context not in annotations: it discloses that auto-generated stacks derive from '5,000+ compatibility pairs' with 'verified or inferred compatibility data,' helping the agent understand data quality and completeness. It does not mention pagination 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?

The description is well-structured with the purpose front-loaded in the first sentence, followed by definitional context. The third sentence providing compatibility data details is informative rather than wasteful, though slightly specific for a high-level description.

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

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

Given the tool has zero parameters, an output schema (removing the need to describe return values), and read-only annotations, the description adequately covers the conceptual domain by explaining what 'stacks' represent in this context. It successfully characterizes the data model (curated vs. auto-generated).

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 zero parameters in the input schema, the baseline score applies. The description appropriately requires no additional parameter clarification since the tool accepts no arguments.

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

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

The description opens with a specific verb ('List') + resource ('stacks') + scope ('all stacks on IndieStack'), clearly defining the tool's function. It distinguishes from siblings by characterizing stacks as 'curated bundles and auto-generated combinations' rather than individual tools or compatibility checks.

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?

While the description explains that stacks are 'pre-built combinations,' implying they are existing configurations rather than new creations, it lacks explicit guidance on when to use this versus `build_stack` (creation) or `find_tools` (individual discovery). The usage is implied through the data description but not stated 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?

Annotations declare readOnlyHint=true, confirming safe read operation. Description adds sorting behavior ('sorted by popularity') not present in annotations, but does not disclose pagination limits, rate limits, or cache behavior. Given annotation coverage, this provides baseline acceptable behavioral context.

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 sentences total with zero waste: (1) core purpose, (2) granularity contrast with examples, (3) consumption instruction, (4) workflow sequencing. Front-loaded with action verb, excellent information density.

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?

Tool has zero parameters and output schema exists (per context signals), reducing description burden. Coverage is complete: explains what tags are, how they relate to categories, workflow integration with list_categories/find_tools, and provides concrete examples ('react', 'rust', 'cli').

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?

Input schema has zero parameters (empty properties object). Per rubric, 0 params establishes baseline score of 4. Description appropriately does not invent parameter semantics where none exist.

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 opens with specific verb 'List' and resource 'tags', explicitly stating scope ('across IndieStack tools') and ordering ('sorted by popularity'). It clearly distinguishes from sibling list_categories by contrasting granularity ('Tags are more granular than categories').

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

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

Provides explicit workflow guidance: 'Use list_categories() first... then list_tags()' establishes prerequisite relationship with sibling. Also specifies consumption pattern: 'Pass a tag to find_tools(tags=...)' linking to another sibling tool. Clear when-to-use within category exploration workflow.

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 indicate readOnlyHint=false. The description adds critical behavioral context: the submission requires team review before going live and that listing is free. However, it omits idempotency details, rate limits, or specific side effects beyond the review queue.

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?

Well-structured with clear sections: purpose statement, usage timing, trigger phrases, and parameter documentation. Every sentence serves a distinct function. The Args block uses consistent formatting and provides specific examples without verbosity.

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 7 parameters with zero schema coverage, the description successfully documents all inputs via the Args section. Since an output schema exists, the description appropriately omits return value details. The cross-reference to list_categories() demonstrates awareness of the tool ecosystem.

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 0% schema description coverage, the description comprehensively compensates via the Args section. It documents all 7 parameters with examples (e.g., 'Plausible Analytics'), format constraints (e.g., 'max 100 chars', 'comma-separated'), and cross-references to sibling tools for valid category slugs.

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

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

The description opens with a specific verb ('Submit'), clear resource ('developer tool'), and destination ('IndieStack'), immediately distinguishing it from sibling discovery tools like browse_new_tools or find_tools. The scope ('so AI agents and developers can discover it') clarifies the end goal.

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

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

Provides explicit temporal guidance ('Use this after the user builds...'), concrete trigger phrases ('I just built X', 'I made Y'), and references a prerequisite sibling action ('Use list_categories() to see valid slugs'). The review process note sets correct expectations.

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 readOnlyHint: false annotation indicates a write operation, and the description adds valuable context about the behavioral purpose ('helps IndieStack track which tools are most useful') and authentication requirements. It does not contradict the annotation.

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 appropriately front-loaded with purpose and timing, followed by behavioral context and parameter details. The 'Args:' section, while unconventional for MCP descriptions, is necessary given the schema deficiencies. 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 tool's simplicity (2 parameters, 1 required) and existence of an output schema, the description adequately covers invocation context, authentication, and parameter semantics. It appropriately omits return value details since the output schema handles that.

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 0% schema description coverage, the description fully compensates by documenting both parameters in the 'Args:' section. It adds crucial semantic context for tool_slug ('from find_tools/get_tool_details results') linking it to sibling tools, and clearly explains query_context's purpose.

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

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

The description opens with the specific verb 'Record' and clearly identifies the resource (recommendation tracking). It distinctly differs from sibling tools like find_tools, compare_tools, or get_tool_details by focusing on post-recommendation analytics rather than discovery or evaluation.

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

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

Provides explicit temporal guidance ('Call this AFTER you recommend') and prerequisites ('Requires an API key'). However, it could strengthen this by explicitly contrasting with report_outcome (another sibling that sounds similar) to clarify this is for tracking recommendations versus reporting integration results.

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 provide only title, so description carries full burden. Adds valuable context about side effects ('Builds the compatibility graph'). However, missing idempotency guarantees, error conditions, or data retention policies that would help an agent understand failure modes or retry 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?

Three declarative sentences followed by structured Args block. No filler text; every sentence conveys essential purpose, timing, or behavioral effect. Front-loaded with the core action.

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?

Appropriate for a 2-parameter reporting tool. Covers invocation trigger, expected inputs, and system effect. Since output schema exists (per context signals), the description appropriately omits return value details. Minor gap in explicit sibling differentiation.

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 0% schema description coverage, the Args section effectively compensates by documenting both parameters: identifies acceptable formats ('Slug or name') and semantics ('first tool' vs 'second tool'). Would benefit from explicit mention of whether order matters or if tools are interchangeable.

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?

Clear verb ('Report') and resource (compatibility between tools), with specific context ('IndieStack tools'). Explains the effect ('Builds the compatibility graph'). Lacks explicit differentiation from siblings like check_compatibility or confirm_integration, though the 'after successfully integrating' timing provides implicit 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?

Explicit temporal guidance ('Call this after successfully integrating') provides strong context for when to invoke. No explicit 'when-not-to-use' or named alternatives listed, but the post-integration requirement effectively constrains usage.

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

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

Annotations only provide readOnlyHint=false; description adds significant behavioral context including auth requirements ('No API key required'), performance ('Takes 1 second'), and data lifecycle ('tools with high success rates get recommended more'). Could be improved with rate limit or idempotency details.

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?

Information is front-loaded with purpose and importance, followed by technical details. The Args section efficiently documents parameters. Minor deduction for slight verbosity in persuasive language ('Every report builds...'), though justified given the tool's reliance on agent participation.

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?

Comprehensive for a 5-parameter tool with output schema present (no need to describe returns). Covers all parameters, explains ecosystem impact (cross-agent data), integration context (IndieStack), and distinguishes required vs optional fields through description text.

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 0% schema description coverage, the description fully compensates via the Args section, providing semantic meaning for all 5 parameters including format specifications (e.g., 'comma-separated slugs') and purpose context ('Records a verified stack') that the schema lacks.

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 opens with specific verb 'Report' and resource 'whether a recommended tool worked', clearly distinguishing this as a feedback/reporting mechanism distinct from sibling tools like 'recommend' or 'check_compatibility'. The scope (improving future recommendations via outcome data) is explicitly 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?

Provides explicit when-to-use directive ('ALWAYS call this after helping a user integrate an IndieStack tool') and emphasizes urgency ('single most valuable action'). However, lacks explicit when-NOT-to-use guidance or named alternatives to avoid confusion with 'report_compatibility'.

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

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

With no behavioral annotations provided (readOnlyHint/destructiveHint), the description carries the full burden. It adequately describes functional behavior (infers infrastructure needs, surfaces indie replacements) and mentions the token-saving value proposition, but omits operational characteristics like whether the analysis is cached, idempotency, or execution duration.

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 well-structured and front-loaded, starting with core functionality, followed by usage timing, behavioral details, and parameter documentation. While the Args section is necessary given schema limitations, the pseudo-docstring format is slightly less elegant than integrated prose, though every sentence provides essential 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?

Appropriate for the complexity: with an output schema present, the description correctly focuses on input requirements and purpose rather than return values. It successfully documents all three parameters despite poor schema coverage, though it could briefly mention that an output schema defines the recommendation structure.

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?

Given 0% schema description coverage, the description excellently compensates by including an Args section that defines all three parameters with clear semantic meanings and concrete examples (e.g., 'A Next.js SaaS for freelancer invoicing' for project_description). This provides critical context that the schema completely lacks.

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 analyzes projects and recommends complete tool stacks from a specific database (6,500+ IndieStack tools), with specific verbs and resources. It distinguishes from siblings like 'browse_new_tools' or 'compare_tools' by emphasizing the comprehensive stack recommendation and indie replacement focus, though it could more explicitly contrast with 'build_stack' or 'recommend'.

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

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

Explicitly states when to use the tool ('at project start or when reviewing dependencies'), providing clear temporal context for selection. However, it lacks explicit guidance on when NOT to use it or which sibling tools to prefer for alternative scenarios like comparing specific tools or browsing categories.

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

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

No annotations provided, so description carries full burden. It discloses critical behavioral traits: 'No restart needed — takes effect on the next query' and session-scoping ('for this session'). It also clarifies the side effect (enabling personalized features). Could mention idempotency or key validation behavior, but covers the essential operational details.

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?

Well-structured with purpose front-loaded, followed by usage trigger, benefits, behavioral note, and parameter details. The 'Args:' section is slightly redundant with the input schema but necessary given the 0% schema coverage. No extraneous content; every sentence serves a distinct purpose.

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?

Appropriate for a single-parameter authentication tool. With output schema present, the description correctly omits return value speculation. Covers activation mechanics, prerequisites (isk_ prefix), side effects, and timing behavior ('next query'). Complete given the tool's limited complexity.

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

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

Schema description coverage is 0% (only title 'Key' provided). The description fully compensates by specifying the format ('starting with isk_') and acquisition source ('get one at indiestack.ai/developer'), adding essential semantic meaning that the schema completely lacks.

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

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

The description opens with 'Activate an IndieStack API key for this session' — a specific verb ('Activate'), resource ('API key'), and scope ('for this session'). This clearly distinguishes it from sibling tools like analyze_dependencies or find_tools, which handle data retrieval rather than authentication setup.

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

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

Provides explicit trigger condition: 'Call this when the user provides their API key (starts with isk_)'. Also explains the benefit ('enables personalized recommendations and migration intelligence'). Lacks explicit 'when not to use' or named alternatives, though the trigger condition is sufficiently specific for an auth utility among functional tools.

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 specify readOnlyHint:false; the description adds crucial behavioral context including authentication requirements ('Requires an API key') and the side effect (generating analytics signal). It also notes the data limit (max 10 slugs). No contradiction with 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?

Front-loaded with purpose statement, followed by usage trigger, value justification, auth requirements, and parameter docs. Efficient structure with no wasted words, though the Args section is utilitarian rather than narrative.

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 (2 flat parameters, output schema present), the description is complete. It covers purpose, invocation trigger, auth needs, and parameter semantics without needing to explain return values since output schema exists.

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 0% schema description coverage, the description fully compensates by documenting both parameters in the Args section: 'tool_slugs' includes type (list) and constraint (max 10), while 'query_context' explains semantic purpose ('What the user asked for').

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

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

The description opens with a specific verb ('Record') and clear resource ('which tools you considered'), explicitly defining the tool's analytics/logging function. It clearly distinguishes from siblings like 'recommend' or 'get_recommendations' by emphasizing this records evaluation choices rather than generating 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?

Provides explicit when-to-use guidance ('Call this when you evaluate multiple tools for a user's request') and explains the value proposition ('helps IndieStack understand demand patterns'). Could be strengthened by explicitly contrasting with siblings like 'recommend' or 'report_outcome', but the context is clear.

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