IndieStack

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.