Buy My Agent

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

Annotations already cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well established. The description adds useful context by clarifying it returns PUBLIC data (as an anonymous visitor sees it) and never the private access link, which is a meaningful behavioral boundary. It doesn't disclose return format details, but with a full output schema and rich annotations, the bar is lower and the added scope constraint earns a solid 3.

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 compact, well-structured sentence delivers the core action, scope, public/private boundary, and the anonymous-visitor framing. Zero waste, strong front-loading, every clause 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?

With a full output schema, strong annotations (readOnly, idempotent, non-destructive), and a single fully-documented required parameter, the description is adequate. It adds the key nuance about public-vs-private data that completes the agent's understanding. The tool is simple (1 param, no nested objects), and there are no obvious gaps for a well-scoped GET 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?

Schema coverage is 100%, so the parameter 'id' is already fully described in the schema as the agent/listing id from search/list tools. The description adds a small nuance by calling it an 'active listing' id, but doesn't go beyond the schema meaningfully. Per the baseline rule for >80% coverage, a 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 uses a specific verb ('Fetch') plus a precise resource (one active listing's full PUBLIC details by its id). It clearly distinguishes from siblings by emphasizing 'PUBLIC details' and 'never the private access link', which meaningfully contrasts with search/list tools. Reference to 'active listing' adds scope clarity beyond name and title.

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 this tool is for retrieving a single listing's full public data by id, contrasting with sibling list/search tools that return multiple results. It clearly excludes the private access link, setting a boundary on what can/cannot be retrieved. However, there's no explicit statement of when to use this vs. when to avoid (e.g., what to do if you need private details), so it falls short of an explicit when-not/alternative 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds the 'active listings (public cards)' filter and 'catalogue browsing' framing, which is useful behavioral context, but doesn't mention pagination behavior or ordering beyond what schema notes.

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 concise sentences, zero filler. 'List active listings (public cards), optionally filtered by category' front-loads the purpose; 'For browsing the catalogue' provides context. Every word 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?

This is a filtered, read-only list tool with strong annotations (readOnly, idempotent, openWorld) and a rich schema covering 100% of parameters, plus an output schema for return values. Pagination is handled via schema's nextOffset note. The description is complete for 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?

Schema coverage is 100%, with all three parameters well-documented in the input schema (limit range/default, offset with nextOffset pagination hint, category tied to list_categories). The description adds no parameter detail beyond schema, 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?

Specific verb+resource ('List active listings'), clarifies scope (public cards) and what it's for ('For browsing the catalogue'). The 'active listings' detail distinguishes from potentially listing all agents including drafts/inactive, and it's clearly a browsing tool unlike edit/search 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?

The 'For browsing the catalogue' phrase gives clear intent, and the category filtering parameter ties to list_categories. However, it doesn't explicitly contrast with search_agents (which likely does more targeted querying), so it stops short of a full when-to-use/when-not-to-use distinction.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds context about the filter-as-companion relationship but does not reveal what the returned categories look like (structure, count, pagination). With annotations carrying the safety burden, a 3 is appropriate.

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?

A single polished sentence carrying purpose, scope, and usage guidance with zero waste. Highly front-loaded and efficient for the agent to parse.

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 zero parameters and a simple enumeration purpose, the description is complete for selecting and invoking the tool. An output schema exists (though its content is not shown), which shifts the burden off the description for return-value documentation. Slightly more detail about returned category format could nudge this to 5, but it's adequately complete.

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 0 parameters, and the description does not need to explain any. The baseline of 4 for zero-parameter tools applies, and the description correctly stays silent since there is nothing to parameterize.

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+resource ('List the marketplace's categories') and immediately clarifies its purpose is 'for use as a filter with list_agents,' which clearly distinguishes it from sibling tools like get_agent, list_agents, and search_agents. The scope is unambiguous.

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 explicitly states when to use this tool — as a filter companion to list_agents — which orients the agent to the integration context. It implies it is a supporting/enumeration tool rather than the primary listing, distinguishing alternatives 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by flagging 'public data only — never the private access link,' a genuinely useful behavioral disclosure about data scope. However, it doesn't describe result ranking details, output shape, or any other behavioral traits beyond that single constraint.

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 sentences, zero waste. The first sentence states purpose, the second conveys the key data-scope caveat. Every word earns its place and the critical behavioral note (private access link) 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 search tool with a 100%-covered schema, good annotations, and an output schema present, the description is largely complete. The main gap is that it doesn't clarify how it relates to siblings (get_agent/list_agents) for disambiguation, but given the schema richness and annotations, what's provided is 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?

Schema description coverage is 100%, so all three parameters (query, limit, offset) are well documented in the schema itself. The description adds the notion of pagination via offset/nextOffset and the natural-language nature of 'query', but largely reinforces what the schema already conveys. Baseline 3 is appropriate given full 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 description clearly states what the tool does: 'Search the Buy My Agent marketplace catalogue by natural-language query.' It specifies the resource (marketplace catalogue), action (search), and the method (natural-language query). It also distinguishes itself from siblings like list_agents (which presumably has a different retrieval mechanism) by emphasizing the natural-language query mode.

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 clarifies it returns 'active listings ranked by relevance' and that it searches by natural-language query, which implies when to use it (user has a natural-language intent rather than a known entity). It doesn't explicitly name alternatives or exclusions (e.g., when to use get_agent or list_agents instead), but the query-oriented framing conveys the intended use case reasonably well.

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