proofstack

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

No annotations are provided, but 'Fetch' clearly signals a read-only retrieval, and the description goes further by listing the returned content categories, including 'what NOT to copy' and evidence sources with URL and grade. It doesn't cover error or rate-limit behavior, but for a simple single-record fetch the key behavioral aspects are present.

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?

One dense sentence with no filler, front-loaded with the action and resource, and every listed element earns its place by telling the agent what data it will receive.

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

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

With only one required parameter and no output schema, the description sufficiently outlines the return contents. It could mention the exact response container or error behavior, but the tool is simple enough that nothing critical is missing.

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

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

The input schema already documents the single slug parameter, and the description adds a concrete example ('tally-forms') plus a pointer to search_cases for finding valid slugs. That is meaningful value 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 opens with a specific verb and object: 'Fetch one audited case by slug', then enumerates exactly what the case contains (pricing tiers, paid trigger, copy guidance, evidence sources). This distinguishes it from search_cases, which is for discovering slugs.

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 parameter description explicitly says slugs can be found via search_cases, establishing a clear search-then-fetch workflow. It doesn't explicitly state when not to use the tool or how pricing_benchmarks relates, so it falls short of full exclusion 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the data source (published pricing pages of audited cases), the exclusion rule (products without public price are excluded, not estimated), and the absence of ranking/traffic figures, all with reasoning. This goes well beyond a minimal description, though it does not mention freshness, update cadence, or output structure.

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 tightly packed sentences with no filler. The first sentence enumerates the concrete statistical outputs, and the second provides essential limitations and exclusions. Every phrase earns its place, and the core information is front-loaded.

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

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

For a simple read-only analytics tool with one optional parameter and no output schema, the description gives enough to understand the returned aggregate metrics and the methodological scope. It could go further by explicitly describing how the category parameter interacts with the output, but the schema covers the parameter and the listed statistics imply the response fields.

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

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

The schema already documents the single optional category parameter fully with an example and the omit behavior. The tool description adds no parameter-specific detail, but since schema coverage is 100%, the baseline of 3 applies; the description's methodological context is useful but not required for parameter understanding.

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

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

The description names a specific deliverable (pricing statistics) and enumerates exactly what is computed: median first paid tier, free-tier prevalence, and paywalled capabilities. It is clearly differentiated from the siblings by focusing on aggregate library-level benchmarks rather than individual case retrieval or search, and it explicitly rules out ranking/traffic data.

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 aggregate pricing statistics are needed and clarifies the data boundary (public prices only), but it never explicitly says when to use this tool versus get_case or search_cases. No alternatives are named and no when-not-to-use conditions are stated, leaving the selection logic to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It meaningfully discloses that cases are audited, include revenue and pricing claims tied to public sources with evidence grades, and explicitly state what does not transfer to other builders. This goes beyond the obvious 'search' behavior and helps the agent set expectations about result quality and limitations.

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 two sentences with no filler. The first sentence front-loads the action and scope, while the second adds valuable behavioral context about evidence grades and non-transferable insights. 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?

There is no output schema, so the description must convey what results will contain. It does that well by stating that each case carries revenue/pricing claims, public-source links, an evidence grade, and an explicit non-transfer list. It could also mention relationship to siblings or return format, but the core information needed to invoke and interpret results is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema; the schema already explains that query accepts keywords like product names, categories, or business questions, and that category is an optional exact filter.

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 a specific verb and resource: 'Search ProofStack's audited business-model case studies of small software products.' It clearly identifies what the tool does and hints at differentiators—audited claims, evidence grades, and non-transferable lessons—that distinguish it from siblings like get_case and pricing_benchmarks.

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

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

The description implies when to use the tool: when searching for case studies by keywords such as product, category, or business question. However, it does not explicitly address when not to use it or how it compares to get_case or pricing_benchmarks, leaving routing decisions to inference.

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