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

Annotations already mark this as read-only and open-world, but the description goes well beyond that: it discloses the coverage-list nature, the absence of rank/rankPoints, the meaninglessness of record order, the inclusion of observed_at and discovery source, and full provenance fields. This gives an agent crucial understanding of what the data does and does not represent.

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 longer than minimal, but each sentence adds value: scope, coverage-not-ranking caveat, record contents, usage direction, on_rank_board nuance, and provenance. It is front-loaded with the core purpose and does not contain filler. It could be tightened by removing slight redundancy around 'Discovery Index,' but overall it is structured effectively.

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 seven optional parameters, no output schema, and many sibling tools, the description does a solid job by explaining record contents and the crucial non-ranking semantics. It lacks explicit differentiation from siblings like get_ai_tools or search_products, and it does not fully enumerate all output fields, but the essential information for correct invocation 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 schema already fully documents all seven optional parameters. The description adds context around the fixed category ('agents') and the on_rank_board field, but it does not add meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 resource: 'Return AI-agent products from the Harpd AI Agent Index.' It precisely scopes the tool to the 'agents' category slice and explicitly separates it from ranking tools by stating it is 'NOT a ranking.' This makes it easy for an agent to distinguish from siblings like get_rankings or get_category_ranking.

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

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

The description gives clear usage context: 'Use this to find AI agent products, their domains, one-line titles and where they were discovered.' It also implicitly tells when not to use it for ranking purposes by emphasizing there is no rank or rankPoints. However, it does not explicitly name alternative tools for ranking or for non-agent products, so some inference remains.

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 read-only and open-world behavior, and the description adds meaningful beyond-annotation context: this is a coverage list, not a ranking, records carry no rank or rankPoints, and order implies nothing about quality. It also discloses provenance behavior and returned fields.

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 moderately sized and front-loads the core purpose and scope before caveats. It is slightly repetitive in enumerating record fields and provenance twice, but every sentence contributes useful 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?

For a read-only list tool with strong annotations and fully documented parameters, the description covers the dataset size, category scope, non-ranking semantics, returned fields, and provenance. An agent has enough context to call it correctly without an output schema.

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 schema fully documents all 7 parameters. The description does not add parameter-level detail, so the baseline of 3 applies; it usefully confirms the record fields but not parameter semantics.

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

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

States a specific verb ('Return') and resource ('AI tooling products from the Harpd AI Tools Index') and precisely scopes the slice by category. It also explicitly differentiates this from a ranking, which distinguishes it from sibling ranking 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?

Clearly says 'Use this to retrieve the current AI tools dataset' and describes the intended data slice. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to choose appropriately among siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: the CRITICAL warning that rankPoints are promotional placement, not quality scores; the structured found:false result for unknown categories instead of an error; and the promise that every record carries full provenance. This is exactly the kind of non-obvious behavior an agent needs to know.

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 compact and front-loaded: the first sentence states the core function, and the critical warning about rankPoints is placed prominently. The provenance sentence is slightly redundant with the openWorldHint annotation but adds useful context. Every sentence earns its place, though the warning could be slightly tightened.

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 read-only list tool with 100% schema coverage and no output schema, the description covers the essential behavior: what is returned, the critical semantic warning, and the error behavior for unknown categories. It doesn't describe pagination details (though limit/offset are in the schema) or the exact shape of the board metadata, but those are either in the schema or not required for correct invocation. A 4 is fair because the description is complete enough for an agent to call it correctly without surprises.

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 schema already documents all four parameters (category, sort, limit, offset) with types, defaults, and constraints. The description adds the semantic warning that sort=rankPoints is NOT a quality ordering, which is valuable context beyond the schema. However, it doesn't add much about the category parameter beyond what the schema already says, so 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 states a specific verb ('Read'), a specific resource ('one of the 28 published Harpd Rank category boards'), and exactly what is returned (board metadata plus listed products). It also distinguishes itself from siblings by naming the resource type (category board) and the fixed set of 28 boards, which is enough to tell it apart from get_product, search_products, and get_rankings.

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

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

The description gives clear context for when to use this tool: to read a category board and its products. It does not explicitly name sibling alternatives or say 'use search_products instead when...', but it does specify the scope (one of 28 published boards) and the behavior for unknown categories, which implies when it is appropriate. A small gap: no explicit exclusion of when to use get_rankings or get_ranking_history 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses key behaviors: this is a coverage list rather than a ranking, order implies nothing about quality, and every record includes observed_at, discovery source, profile URL, and full provenance. This gives the agent useful expectations about data completeness and limitations without contradicting 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 is dense but efficient: it front-loads the resource and scope, then adds the crucial non-ranking caveat, a concrete usage line, and provenance details. Every sentence earns its place, with no filler or repetition of schema 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?

For a read-only list tool with 7 schema-documented parameters and no output schema, the description provides the missing return-value context: record contents, provenance, and the non-ranking nature of the data. Together with the schema and annotations, this is sufficient for an agent to select and invoke the 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?

The input schema already documents all 7 parameters with 100% coverage, so the baseline is 3. The description adds minor context by mentioning matching against name, domain, or description and confirming the developer category, but it does not materially enrich parameter semantics 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 resource: 'Return developer-tool products from the Harpd Developer Tools Index.' It further pins the exact slice ('Discovery Index slice where category = "developer"') and explicitly separates this from ranking tools by stating it is NOT a ranking. This clearly distinguishes it from sibling tools like get_rankings or get_ai_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 gives explicit use guidance: 'Use this to find developer tools, SDKs, infra and dev platforms by name, domain or description.' It also implicitly warns against using it for ranked comparisons by saying records 'carry no rank and no rankPoints.' It does not name alternative sibling tools or state when not to use it, so it falls just short of full routing 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 annotations (readOnlyHint, openWorldHint), the description discloses meaningful behaviors: it returns claims that fail the evidence chain with their violations rather than hiding them, includes claims Harpd explicitly does not make, and records that rankPoints are promotional placement bought with Credits, not an editorial quality score. This adds rich context beyond the structured 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 front-loaded with the core purpose, followed by usage guidance and important behavioral caveats. Every sentence earns its place: purpose, use case, rankPoints clarification, violation handling, and provenance. The length is justified by the tool's complexity and the need to prevent misuse.

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?

Despite having no output schema, the description explains what is returned (evidence, dataset, methodology, source, timestamp, provenance, violations, non-claims) and clarifies critical domain facts. Combined with the comprehensive input schema and annotations, an agent has enough context to invoke this tool correctly and interpret results.

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 parameters are already fully documented. The description does not add parameter-specific semantics (e.g., how query or productName interact with the evidence graph), but it does add domain context like the rankPoints caveat. Baseline 3 is appropriate because the schema carries the parameter details.

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

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

States a specific action ('Query the Harpd Evidence Graph') with a clear resource and scope: every published claim resolved to evidence, dataset, methodology, source, and timestamp, including claims not made. This distinguishes it from sibling tools like get_product or get_rankings, which focus on products or rankings rather than evidence-backed claims.

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?

Gives clear context on when to use the tool: 'Use this to check whether a statement about Harpd data is actually supported before repeating it.' It does not explicitly name alternatives or exclusion conditions, but the usage scenario is well defined and implies this is the evidence-verification tool among the siblings.

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 readOnlyHint and openWorldHint already provided, the description adds useful non-obvious behavior: missing products return a structured found:false result rather than an error, and rankPoints are explicitly de-mystified as promotional, not editorial quality. These disclosures go beyond annotations and meaningfully shape how an agent interprets results.

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 three sentences with no filler: it states the primary use, the return contents, the not-found behavior, and a critical note about rankPoints. All sentences earn their place, though the provenance list is slightly dense and could be simplified.

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

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

The description covers return fields, not-found behavior, and rankPoints, but it never states that at least one of id/slug/name must be supplied (the schema marks all as optional, yet the tool is unusable with zero parameters). This is a critical operational gap. The description also omits match semantics for 'name', though those appear in the schema, so the gap is partially mitigated.

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

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

The schema has 100% description coverage for all three parameters, and the tool description only restates that lookup is by id, slug, or name. It adds no parameter-specific meaning beyond what the schema already documents, so the baseline of 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 states a specific verb ('Look up') and a specific resource ('a single product... by id, slug or name'), which clearly differentiates it from siblings like search_products and get_products. The title and description both emphasize the singular-product scope, leaving no ambiguity about what the tool does.

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 single-product lookups by identifier, but it never explicitly says when to choose this over search_products or get_products. There are no exclusions or alternative routing instructions, so the agent must infer from the sibling names rather than being told.

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 signal readOnlyHint and openWorldHint, but the description adds substantial extra behavioral context: rankPoints are promotional placement bought with Credits, not an editorial quality score, sorting by rankPoints is a non-merit ordering, page size is capped at 200, and every record carries full provenance. This meaningfully exceeds the annotation coverage.

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 compact and every sentence earns its place: primary purpose, usage routing, the critical rankPoints caveat, pagination cap, and provenance note. The most decision-relevant information (what it is and when to use it) 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?

Despite having 8 parameters and no output schema, the description gives an agent everything needed to invoke the tool correctly: scope, filters, pagination behavior, sorting semantics, and the distinction from search_products. The provenance note partially compensates for the absent output schema by setting expectations about record completeness.

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 the baseline is 3. The description adds value by warning that sorting by 'rankPoints' orders by promotional placement rather than merit, which directly enriches the most subtle parameter. It also summarizes the filter dimensions (category, verification, product type, rankPoints range), but the schema already covers those clearly.

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 verb ('Page through') and resource ('full Harpd open product catalog'), and explicitly distinguishes itself from search_products as the enumeration/bulk-export path. This leaves no ambiguity about what the tool does or how it differs from its closest sibling.

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 states when to use this tool ('Use this to enumerate or bulk-export products') and explicitly routes users away from it for free-text lookup ('use search_products for free-text lookup'). This provides clear selection guidance against the main alternative.

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 mark this as read-only and open-world, and the description adds substantial behavioral context: only three live period-scoped snapshots exist, no historical time series is available, and rankPoints represent purchased promotional placement rather than quality. This materially prevents misinterpretation of results.

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 with the core purpose, with clearly labeled warnings for the most important caveats. There is minor redundancy in repeating the 'not a time series' point in both title and description, but the emphasis serves a real safety 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?

For a read-only tool with no output schema, the description explains what the tool can and cannot return: exposed periods plus an explicit limitation statement. It also clarifies the meaning of rankPoints. It could describe the exact result layout or how productId versus productSlug is resolved, but the essential calling context is covered.

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 schema already explains each parameter. The description reinforces the board comparison context but does not add per-parameter meaning beyond what the schema provides, fitting the baseline for high schema coverage.

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 verb 'Compare' plus the direct object 'the three published Harpd Rank board snapshots (overall / monthly / weekly)' specifies exactly what the tool does. The title's '(NOT a time series)' and the discussion of product-level versus board-level comparison distinguish it from ranking/history 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?

It states when to use the tool (comparing snapshots for one product or side by side at board level) and is emphatic about when not to use it (month-over-month trends, because no multi-month time series exists). It does not name an alternative sibling tool, but the exclusion is unambiguous.

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 and openWorldHint. The description goes well beyond by explaining that rankPoints are promotional placement, not quality scores, and that ordering by rank is also derived from promotional placement. It also discloses the live-snapshot nature, which complements the openWorldHint. This is critical behavioral context that prevents misinterpretation of results.

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, leading with the core purpose, then the critical caveat about rankPoints, then the snapshot nature. Each sentence earns its place, and the CRITICAL flag draws attention to the most important trap. It is appropriately sized for the complexity of the tool.

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

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

The description covers the key pitfalls and usage constraints, but it does not describe the return structure or what 'period metadata' entails, which could be useful given there is no output schema. However, the critical semantics about sorting and board types are well covered, and the lack of output schema is offset by the clarity of the description. Minor gap, but overall complete for safe 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?

Schema coverage is 100%, so the baseline is 3. The description adds significant value for the 'sort' parameter by warning that 'rankPoints' is not a quality ordering and that 'rank' also reflects promotional placement. This is crucial beyond the schema's terse description. It does not add details for limit/offset/category, but those are adequately described 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 clearly states the tool reads one of three published Harpd Rank boards and returns period metadata. It uses a specific verb ('Read') and resource ('Harpd Rank boards'), and distinguishes itself from historical time-series tools by emphasizing it is a live snapshot. This differentiates it from siblings like get_ranking_history without naming them explicitly.

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

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

The description provides context on when to use the tool: reading published boards for a given period, not historical data. It explicitly states the board is not a historical time series, implying an alternative exists, but it does not name get_ranking_history or get_category_ranking. The CRITICAL note about rankPoints also guides appropriate use, but there is no explicit when-not-to-use list.

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/openWorldHint annotations, the description supplies rich interpretive context: pointsShare is a share of promotional rankPoints bought with Credits, explicitly NOT an editorial quality or market-merit score. It also discloses data-availability constraints (reports exist only for closed months with enough ranked products) and asserts full provenance on every record, which materially prevents misuse.

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 front-loaded with the resource scope and then delivers two high-value caveats (pointsShare semantics and closed-month availability) that prevent real misinterpretation. It is slightly longer than strictly necessary - the quality-score point is restated twice ('NOT an editorial quality score' and 'not a share of quality or of market merit') - which keeps it from a perfect score.

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 no output schema, the description carries the burden of explaining return values, and it does so at a useful level: record counts, row semantics, the meaning of share fields, and availability constraints. Combined with the readOnly/openWorld annotations and fully documented parameters, an agent has what it needs to call this correctly; only per-field detail of the report records is left unspecified.

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 the input schema already documents all six parameters, and the description adds no parameter-specific guidance beyond it. The 'IMPORTANT' caveat clarifies the semantic meaning of an output field (pointsShare) rather than any input parameter, so the description correctly holds at the high-coverage baseline of 3.

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 resource ('Read Harpd research output') and enumerates exactly what that includes: 5 monthly report records and a 27-row AI Market Index with product counts, product share, and rank-point share. This concrete scope distinguishes it from the product/ranking sibling tools (get_rankings, get_product, get_category_ranking) without needing to inspect any schema.

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 makes the tool's domain clear ('research output... published monthly research reports... market index'), so an agent can infer it is for Harpd's published analysis rather than raw ranking or product data. However, it never names an alternative sibling (e.g., get_rankings or get_evidence) or states when not to use this tool, leaving the guidance implied rather than explicit.

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?

It discloses the non-obvious behavior that rankPoints are paid promotional placement, not editorial quality, which prevents a serious misinterpretation. This adds meaningful context beyond the readOnlyHint/openWorldHint annotations, though it does not address rate limits or exact response formatting.

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 with the main action and key output. The rankPoints warning is valuable but partially redundant with the sort parameter description, making it slightly longer than necessary.

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 no output schema, the description covers the important operational context: catalog size, available filters, ordering semantics, returned fields (rank, rankPoints), and full provenance. This is enough for an agent to call and interpret results 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?

Schema description coverage is 100%, so the schema already documents sort, limit, query, offset, category, and verified clearly. The description mostly repeats the rankPoints warning and lists search dimensions, adding little meaning beyond what the schema provides.

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 verb ('Search'), a specific resource ('the Harpd open product catalog'), and the main search dimensions ('free text, category and verification state'). It also states the return value includes rank and rankPoints, making it distinct from the sibling get_* 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 makes the use case clear: search a broad catalog by free text, category, or verification state, rather than fetching a single product. It does not explicitly say when not to use it or name alternatives such as get_product or get_rankings, so it falls short of full routing guidance.

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