Get AI agents from the Harpd Discovery Index

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.