AgentGid

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds that data is live and sourced from official status pages, and that incident history is limited to 30 days. It says nothing about freshness/latency, behavior on unknown names, or partial failures across the up-to-20 items, and fetching external status pages sits slightly uneasily with openWorldHint=false, though this is a soft rather than outright contradiction.

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 sentence, front-loaded with the core capability ('Live status of agents and APIs'), then the source and time window. No filler or repetition.

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 should say more about the shape of results — per-name status values, incident structure, or error reporting for invalid names. It also leaves batch semantics at maxItems=20 unaddressed. What exists is enough to call the tool, but not enough to interpret the response or predict edge cases.

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 single parameter 'names' has 0% schema description coverage and no description text, so the definition must carry the burden. Mentioning 'agents and APIs' only weakly hints that names are agent/API identifiers; it does not specify accepted forms, matching rules, or what happens with unrecognized names, despite the maxItems=20 cap.

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 concrete verb-and-resource outcome: live status of agents and APIs, plus incidents from the last 30 days. It is distinguishable from read-only siblings like get_agent or get_api, which return entity details rather than health. It stops short of explicitly naming a differentiating sibling or scoping what 'names' refers to.

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?

There is no when-to-use guidance, no conditions, and no mention of alternatives (e.g., get_agent for details vs. this for health). An agent must infer from the word 'status' that this is the health-check tool. The 30-day incident window is the only scoping hint.

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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, and the description still adds real context: results come from the vendor's own page and each entry carries an end date and source, which speaks to provenance and staleness. It omits result count, pagination, and refresh cadence, which keeps it from a 5.

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 tight sentences with zero filler, and the core purpose (active offers, and from whom) is front-loaded before the provenance detail. Nothing needs to be cut.

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 zero-required-parameter, read-only listing tool with no output schema, the description tells the agent what to expect in each result (end date, source) and what the catalog covers. Only minor gaps remain: no pagination or result-volume expectations, and no mention of filtering by vendor.

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% and both parameters are optional and self-documented, so the baseline is 3. The description echoes the `kind`-style categories (discounts, free access, extra usage, credits, student, startup, open-source) but says nothing about the `agent` filter or how the two combine.

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 resource (active official deals/offers from AI agent and tool vendors) and enumerates the categories returned, so an agent knows exactly what this returns. It is distinguishable from data-oriented siblings like model_prices or find_tools, though it never states its verb (list/retrieve) or explicitly contrasts itself with those 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?

There is no when-to-use statement, no exclusions, and no named alternative. The closest thing to guidance is the enumeration of offer categories, which an agent can loosely infer maps to the `kind` filter, but nothing tells it when to pick current_deals over model_prices, price_history, or limit_resets.

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=false, so the safety profile is covered. The description adds real value beyond that: the output is license-checked, what the kit contains, and that it includes a paste-ready AGENTS.md brief. It does not describe result size or whether the kit is deterministic for a given slug.

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?

It is front-loaded with what the tool produces, then lists recipes, then the no-argument behavior. One long enumeration sentence is dense but each item is informative about contents. No filler or repetition.

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 must convey return contents, and it does reasonably well. The gaps are behavioral edge cases: what happens when both `recipe` and `style` are supplied, what a style with no matching recipe returns, and the relationship to list_recipes. For a 2-param read tool these are modest but real omissions.

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 both `style` and `recipe` are already documented in the schema, including the 'best match' semantics of style. The description only restates recipe slugs as examples. Baseline 3 is appropriate since the schema carries the parameter 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 gives a concrete verb+resource: it returns a license-checked kit (UI kit, fonts, icons, colors, art, logos, placeholders, favicon/OG tools, libraries, Agent Skills, plus an AGENTS.md brief) for a chosen site type. It also enumerates the recipe slugs, so the agent can tell what the tool yields. It stops short of differentiating itself from the sibling list_recipes, which overlaps with the 'call with no arguments to list them' behavior.

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 one concrete usage mode — no arguments to list recipes — which implies the argument-taking mode. However, it never says when to reach for this tool versus the sibling list_recipes, nor how to choose between passing `recipe` and `style`. Usage is implied rather than prescribed.

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=false, so the safety profile is covered. The description does add useful behavioral context by naming the five dimensions being compared, which matters because there is no output schema, but it says nothing about result volume, pagination, or ordering.

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 tight sentences with zero filler: the first front-loads the action and the comparison dimensions, the second disposes of filter optionality. Nothing repeats and nothing is buried.

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 comparison tool with annotation coverage and an 80%-documented schema, the description is nearly sufficient, and its enumeration of compared attributes partly compensates for the missing output schema. It stops short of stating return shape or result limits, which would matter for an agent planning a call.

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 80%, so the schema already documents chain, category, mcp_only, and max_price_per_1k. The description only adds 'Filters are optional,' which is baseline-level information already implied by the required array; it adds no syntax or edge-case detail 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?

States a specific verb+resource ('Compare APIs in one category') and enumerates the comparison axes (official price, free tier, MCP support, SDK downloads, status). It clearly separates the tool from single-entity siblings like get_api, but it never names an alternative, so sibling differentiation is only implicit.

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?

'Filters are optional' hints that a bare category call is valid, but there is no explicit when-to-use guidance and no mention of alternatives such as get_api for a single API's details or list_api_categories for discovering the required slug. Usage must be inferred.

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=false, so safety is covered; the description goes further by disclosing the exact dimensions of the result set (price, commercial-use permission, credit requirements, in-app shipping, bot fetching, rules, connection methods). That is meaningful behavioral context beyond the annotations, though it says nothing about result limits or pagination.

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?

It is a single dense sentence front-loading a very long enumeration of asset types before getting to what results actually contain. The content is informative and not padded, but the run-on structure and lack of a leading verb make it harder to scan than it needs to be.

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 correctly compensates by enumerating the fields each result carries (price, license, credit, shipping/bot rules, connection method), which is what an agent needs to judge relevance. It is nearly complete, missing only result-count or pagination behavior.

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 four parameters (query, style, category, free_commercial_only) are already documented in the schema. The description echoes the category domain but adds no syntax, matching behavior, or combination semantics, so baseline 3 applies.

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 identifies the resource domain precisely (sources of UI kits, fonts, icons, illustrations, stock media, 3D) and what each result covers (price, license terms, credit, connection method). It distinguishes itself from the sibling get_asset, which returns 'the full card with the license quotes'. It never states an explicit verb like 'search' or 'find', so the action must be inferred from the tool name.

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 only routing guidance is the closing pointer to get_asset for the full license card, which implies this tool returns summaries. There is no statement of when to prefer it over find_tools, find_apis, or get_asset beyond that single hint, and no exclusion criteria.

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=false, so safety is covered. The description adds genuinely useful return-content context — each result carries API availability, key requirements, downloadability, commercial-use/embedding terms with quotes, and build ideas — which matters because there is no output schema. It says nothing about match semantics, result ordering, or what limit defaults to.

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, front-loaded with the resource scope and followed by the sibling hand-off to get_resource. The long parenthetical catalogue of example domains is dense but does real work in telling an agent what is indexed; "Remarkable" is the only clear filler.

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 seven parameters, no output schema and only two annotations, the description covers what kinds of data come back and where to go for detail, which is the essential part. It stops short of explaining search behavior, limit semantics, or how the boolean filters combine — gaps an agent must discover by trial.

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 86%, so the baseline is 3 and the parameters largely document themselves. The description indirectly signals the filterable attributes by listing API availability, key requirements, downloadability and commercial use, which maps onto the free_api, no_key, commercial and live flags, but it never connects those concepts to the parameters or explains query matching behavior.

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 makes clear this is a discovery tool over a curated collection of "remarkable websites a project can build on" and enumerates the domains covered (live maps, open data, archives, space/science). It also differentiates itself from the sibling get_resource by stating that get_resource returns the full card. The only weakness is the missing explicit verb ("search" or "browse") — the intent is inferred rather than stated.

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?

One routing hint is present: use get_resource for the full card, implying this tool returns summaries. But there is no guidance on when to choose this over find_apis or find_assets, both of which sound adjacent, and no mention of the filter dimensions (live, no_key, free_api, commercial) that would let an agent narrow results deliberately.

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=false, so the safety profile needs no restating. The description usefully adds provenance (public GitHub repos) and hints at the data returned, but discloses nothing about ranking, pagination, limits, or how results are ordered, so it adds only moderate context.

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 front-loaded sentence that packs the resource, applicable agents, data source, and returned fields without filler. It is slightly run-on with the colon-appended field list, but nothing is wasted.

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, and the description does partly compensate by listing the returned fields (coverage, skill count, stars, AgentGid install page). However, the meaning of 'limit', result ordering, and any guidance on narrowing an over-broad query are missing, leaving gaps for a two-parameter lookup tool.

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 50%: 'query' has an in-schema description with examples, but 'limit' is undocumented in both schema and description. The description text adds no parameter meaning at all, not even how query terms are matched, so it fails to compensate for the coverage gap.

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 identifies the resource (Agent Skills packs / SKILL.md for Claude Code, Codex, Cursor and similar agents) and the scope (public GitHub repos), so an agent understands what domain this covers versus find_apis, find_tools, or find_assets. It never states the verb explicitly (search/find), relying on the name and the presence of a 'query' parameter to imply retrieval, so it stops short of a 5.

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?

There is no when-to-use or when-not-to-use guidance and no mention of the sibling find_* tools as alternatives. The only steering is the implicit 'query' example, which is generic rather than an explicit routing rule.

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=false, so safety is covered; the description adds the return shape (candidates grouped by kind, with Gid Score, prices, licenses and links), which is real added value. It stops short of mentioning result count, limit behavior, or what an empty result looks like.

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 purpose and the 'use this first' routing are front-loaded, and the example list earns its space by demonstrating query phrasing. The example list is slightly long and the return-value sentence could be tighter, but nothing is filler.

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 search with no output schema, the description covers what comes back, how it is grouped, and the follow-up path. Only the behavior of 'limit' and empty/zero-result handling are left unstated.

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 50% and 'limit' has only bounds/default with no prose; the description partly compensates by showing the style of 'goal' input through four concrete example queries, which clarifies phrasing and granularity better than the schema's 'in plain words'.

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 (Search) and resource (AgentGid catalog) plus the item kinds covered, and the worked examples ('Solana LP copy-trading bot', 'free fonts for a mobile app') pin down the scope far better than an abstract noun could.

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?

Explicitly instructs 'Use this first, then get_tool / get_asset / get_api / get_agent for the full card', naming the sibling tools and the ordering condition, so the agent knows both when to call this and what to call next.

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=false, so the safety profile is covered. The description usefully discloses what content the record contains (pricing, usage limits, live incidents, release, popularity, safety settings), but says nothing about freshness, auth requirements, or why openWorldHint is false despite covering 'live status'.

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 front-loaded sentence with no filler; the field enumeration is dense but each item earns its place by previewing return contents. Slightly list-heavy rather than prose, but structurally efficient.

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 correctly compensates by enumerating the categories of returned data, which is the main thing an agent needs to judge relevance. It is a simple one-parameter read, so remaining gaps (exact fields, unknown-slug behavior) are minor.

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?

There is a single parameter with 100% schema description coverage ('Agent slug or name'), so the schema already carries the parameter semantics. The description adds no format, slug-syntax, or accepted-value guidance 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 resource (an AI agent or developer tool) and enumerates what the returned details cover (pricing, plan limits, status/incidents, latest release, popularity, safety settings). This clearly separates it from data-oriented siblings such as model_prices or find_apis, though it does not explicitly contrast itself with the close sibling get_api or check_status.

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?

There is no statement of when to call this tool versus alternatives such as get_api or check_status, nor any prerequisites or context for selecting it. The agent must infer usage purely from the resource name and field 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?

Annotations already establish the safety profile (readOnlyHint=true, openWorldHint=false). The description usefully adds the shape of the payload, but says nothing about what happens with an unknown slug, whether lookups are cached, or any rate limits. Adequate but not rich, given annotations carry safety.

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 dense sentence, front-loaded with the resource and immediately followed by the returned field groups. No filler, nothing to trim.

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 indicating return content, and it does so by enumerating the field groups. Minor gaps remain (unknown-slug behavior, whether categories/alternatives are links to other tools), but it is complete enough to call 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 coverage is 100%: the single 'api' parameter is fully documented with a slug/name description and examples (tavily, helius, meshy). The description adds no format or matching nuance beyond that, so the baseline 3 applies.

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 clear verb+resource ('Full details of one API') and enumerates the specific content returned (pricing, SDK packages, MCP server, status, alternatives). This implicitly separates it from list/search siblings like find_apis, but no sibling is named explicitly, so it falls short of a 5.

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?

Usage is only implied: fetch this once you already have an API slug and need deep detail. There is no explicit when-to-use, when-not, or pointer to an alternative (e.g. find_apis for discovery, model_prices for comparison), so the agent must infer the routing.

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=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavioral context by spelling out what the response contains (license quotes, source URLs, prompt lines). It stops short of noting rate limits, caching, or failure behavior for unknown slugs.

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 front-loaded sentence that names the resource first and then enumerates contents; no filler or redundant restatement of the name. The long parenthetical list is dense but every element carries 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?

With no output schema, the description carries the burden of describing the return value and does so thoroughly, and the single parameter is fully covered by the schema. It is complete for a read-only lookup, though the absence of any when-to-use framing leaves a small gap.

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% and the single 'asset' parameter already documents itself with slug examples (google-fonts, kenney, poly-haven). The description adds no format or matching semantics beyond the schema, so the baseline 3 applies.

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 (retrieve) and resource (the full card of a content source) and enumerates the card's contents — price/free tier, license terms, rules, connection methods. It does not explicitly name sibling get_api/get_tool/get_agent or find_assets to differentiate, so it falls short of a 5.

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?

There is no statement of when to call this versus find_assets (search) or the other get_* lookups. The 'full card' phrasing implies a detail-fetch after a search, but the agent must infer that workflow 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?

The annotations already establish that this is a read-only, non-open-world operation. The description adds useful behavioral context by explaining what the returned card contains: API details, example request, key and limits, download options, license quotes, agent rules, and build ideas.

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 definition is a single front-loaded sentence that immediately identifies the tool's output. The long parenthetical and contents list are dense but each item describes useful card content, so there is little wasted text.

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 one-parameter read-only lookup with no output schema, the description is complete enough because it explains the card's contents. The main missing piece is explicit routing guidance versus sibling search/detail tools.

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 schema already documents the single 'resource' parameter. The description adds value by giving concrete examples of resource types such as USGS earthquakes, NASA images, Open Library, and Met Museum, which helps clarify what a valid resource refers to.

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 that this tool returns the full AgentGid card for a single resource, and it lists the card's contents. It is specific about the verb and resource, but it does not explicitly distinguish this tool from nearby siblings such as find_resources or get_api.

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 that this is a detail lookup by saying it returns a 'full card,' but it gives no explicit guidance on when to use it instead of find_resources or get_api. There are no alternatives or exclusions named.

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 establish readOnlyHint=true and openWorldHint=false. Beyond that, the description discloses meaningful behavior: data is cross-checked against the pack's own files at a pinned commit, and the author's stats are explicitly flagged as reported rather than verified. That provenance detail is exactly the kind of trust signal an agent needs; only the response shape is left implicit.

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?

It is front-loaded with the resource and ends with the actionable routing sentence, so the structure is sound. However, the middle is a single sprawling clause listing eight card contents in a row, with a parenthetical and a stray ellipsis, which makes it dense to parse rather than efficient.

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 must convey what comes back, and it does so thoroughly by enumerating the card's sections, including security-relevant ones (hooks, files written, network access). What is missing is only minor: the granularity of the per-skill list and whether uninstall instructions are always 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 coverage is 100% and the schema's own example (DietrichGebert/ponytail, ponytail-review) documents the accepted identifier forms. The description only implies that the argument identifies a pack or skill and does not add resolution rules or fallback behavior beyond that. Baseline 3 applies when the schema carries the parameter 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 states a specific resource and scope: the detail card for one Agent Skills pack, verified against the pack's own files at a pinned commit. It enumerates the card's contents (purpose, per-skill file mutation, install/uninstall commands, local execution surface), which distinguishes it from the sibling find_skills. The jargon 'AgentGid card' adds a little noise, but the substance 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 closing sentence gives an explicit workflow: search with find_skills, then call get_skill before installing a pack, naming the sibling to use instead for discovery. The 'before installing' framing supplies the triggering condition, not just a vague suggestion.

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=false, so the safety profile is covered and the description correctly doesn't contradict it. The description adds real value by disclosing the shape of the returned card (install line, version, license, warnings, rules, docs, Gid Score, downloads, alternatives), which partly compensates for the missing output schema, but it says nothing about failure behavior for unknown slugs or data freshness.

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 core statement is front-loaded and correct, but the rest is a single sprawling sentence with a long parenthetical laundry list of card fields, including vague entries like 'use in projects built with AI agents'. It is information-dense but not well structured or skimmable.

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's enumeration of returned fields is exactly the right compensation and makes the payload predictable. The remaining gap is routing context versus the many sibling lookup tools, which is not addressed.

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?

Only one parameter and schema description coverage is 100%, so the baseline is already high. The description's concrete examples (React, GSAP, Zod, FastAPI, Phaser) reinforce that the identifier is a package/framework name rather than an ID, adding mild but genuine clarification 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?

States a specific verb and resource ('The full AgentGid card of a library, framework or dev tool') and enumerates what the card contains, so the agent knows exactly what it fetches. However, it never distinguishes itself from the sibling find_tools, leaving the retrieve-one-vs-search-many boundary to inference.

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?

No when-to-use guidance at all: nothing says this is the follow-up call once a slug is known, nor when to prefer find_tools/find_apis/get_asset instead. The only implicit hint is that the single 'tool' parameter suggests lookup by known identifier.

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=false, so the safety profile is covered. The description adds return-content context (last reset times, frequency, recent resets with links to announcements), but says nothing about data freshness, caching, or coverage limits — relevant since the value depends on recency.

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 sentence with no filler, and the subject (what was last reset, for which products) is front-loaded. The parallel structure ('When ... how often ... recent resets') is slightly awkward but efficient.

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 one-optional-parameter, read-only informational tool with no output schema, the description adequately conveys what the agent gets back. It is complete enough to call correctly, though it could note the freshness or window of the reset data.

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% and the parameter itself is documented as optional with 'claude-code or codex (default both)'. The description only implicitly confirms both products are covered, adding no syntax or default detail beyond the schema. Baseline 3 applies.

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 distinct resource — usage-limit reset history for Claude Code and Codex — with concrete scope (last reset, frequency, recent resets with announcement links). It is identifiable against siblings like model_prices or real_world_usage, though it is phrased as a sentence fragment rather than an explicit verb+resource statement.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as check_status or real_world_usage. The agent must infer the use case from the description alone.

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=false, so safety and scope are covered. The description contributes nothing further about behavior — no statement that the list is static, whether it can change, or how results are ordered/returned.

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 front-loaded sentence with the verb and resource first. The parenthetical enumeration is long but constitutes the tool's actual payload (the category values), so it earns its place rather than being padding.

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 zero-parameter, read-only enumeration with no output schema, the description effectively discloses the returned values inline, leaving little for an agent to be unsure about. Only the absence of routing guidance to find_apis keeps it from a 5.

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 takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description's enumeration is content, not argument documentation.

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 (List) and resource (categories of APIs) and enumerates the actual taxonomy, so an agent knows exactly what comes back. It is clearly distinguishable from siblings like find_apis, which retrieves individual APIs rather than the category taxonomy.

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 never says when to use this tool versus siblings such as find_apis or find_tools, nor that it should be called first to discover valid category values. Usage is only inferable from the name and the enumeration; no alternatives or exclusions are named.

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=false, so the safety profile is covered. The description adds useful context by enumerating what a 'recipe' contains (id, title, shaping questions, test-build timestamp), but says nothing about result size, ordering, or pagination.

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 front-loaded sentence with the returned fields enumerated after the core statement; the parenthetical example list is somewhat long but serves to make 'recipe' concrete. No filler or repetition.

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 usefully names the returned fields, and with zero parameters there is nothing else structural to document. It is still thin on how this list should feed into downstream tools, leaving the agent to infer the workflow.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify and it correctly avoids inventing filter semantics. The schema description coverage is already 100%.

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 (List) and a well-defined resource: the project types AgentGid has a tested kit for, plus the fields returned (id, title, shaping questions, test-build date). The resource is distinctive enough to separate it from siblings like find_skills or plan_project, though it never names those siblings 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?

There is no guidance on when to call this versus alternatives such as plan_project or find_skills, and no stated prerequisites or ordering. Usage is only implied by the description of the returned content.

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=false, so the safety profile is covered. The description adds useful context that results include pricing units and agent eligibility, but says nothing about result volume, the limit parameter, or ordering.

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 compact sentence with the resource and the filter front-loaded; no filler. It is arguably too terse rather than verbose, but nothing is wasted.

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 and 0% schema coverage, the description adequately conveys what the tool returns but leaves the limit parameter and result-set size undocumented. An agent could call it correctly for the basic case but not optimize paging.

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 0%, so the description must carry both parameters. It only covers 'query' loosely ('filter by name') and completely omits 'limit' (default 15, max 40), leaving the agent unaware of pagination/truncation behavior.

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 resource (LLM API prices) and explains the returned dimensions: per-1M input/output token cost, context, and agent eligibility. It is distinguishable from siblings like price_history, though it never names or contrasts with 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 only usage signal is 'Optional filter by name,' which describes a parameter rather than when to choose this tool. No guidance on when to prefer it over price_history, find_apis, or current_deals, and no exclusions.

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=false, so safety is covered. The description adds real behavioral context beyond that: it never improvises a stack, it refuses and enumerates recipes on a miss, and it specifies the exact output composition including what files=true unlocks.

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?

Front-loaded with the primary outcome ('Get a project kit'), then progressively narrows to contents, input options, and fallback. Dense but every clause carries information; the single long opening sentence is the only mild readability cost.

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 9 documented parameters, no annotations gaps and no output schema, the description does the job of describing return contents (parts with version/license/reasons, install lines, checks, AGENTS.md/CREDITS.md/prompt/setup files). It stops short of noting pagination or size limits, but nothing essential to correct invocation 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already carries the parameter burden. The description reinforces files=true and the recipe-vs-goal input path, but adds little syntax or meaning beyond what the schema's own property descriptions provide.

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 and resource ('Get a project kit', one part per job), then enumerates exactly what a kit contains (versions, licenses, install lines, checks, optional files). It routes to the sibling list_recipes for recipe ids, so an agent can distinguish it from the find_* and list_* tools without opening a 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 explicitly tells the agent how to seed the call — a recipe id from list_recipes or a plain-words goal — and names the sibling that supplies recipe ids. It also covers the failure path ('if no recipe fits the goal, it says so and lists the recipes'), but does not say when to prefer this over alternatives like find_tools or report_kit_issue.

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 grant readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful provenance beyond that — the data comes from archived copies of the official pricing page and is bucketed monthly — which tells the agent the values are historical snapshots rather than live quotes. It stops short of stating coverage depth, update cadence, or pagination.

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 tightly written sentence with the resource up front and the data source trailing. No filler, no restatement of the title.

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 one-parameter read-only lookup with no output schema, the description conveys enough about the return shape (monthly plan/price changes from archived pricing pages) that an agent knows what to expect. It could be stronger by stating how far back the history reaches or how often it refreshes.

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% for the single 'agent' parameter (it already gives a slug format and examples like cursor, claude-code), so the schema carries the parameter burden. The description adds no additional parameter meaning, making the baseline 3 correct.

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 resource (an agent's plans and prices) and a specific dimension (month-by-month change), which an agent can immediately picture. It does not, however, name or rule out the closely related siblings model_prices and current_deals, so differentiation is left to the agent.

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?

Usage is only implied: the 'month by month' framing suggests historical trend analysis rather than a current-price lookup, which weakly routes against model_prices. There is no explicit 'use this when / use X instead' statement or any prerequisite 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 and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the payload shape (cost-to-start, per-minute call cost for voice-agent, paste-ready AGENTS.md brief), which matters because there is no output schema. It does not say how an unrecognized slug is handled.

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, front-loaded with what the tool returns before the slug inventory. The content block is dense with nested parentheticals ("APIs per part (free tier, price, official MCP server and its card)") and the slug list is long, but both earn their place as payload preview and enum substitute.

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 single-optional-param read tool with no output schema, the description is largely sufficient: it explains the return contents and lists valid inputs. The missing piece is the relationship to list_recipes and design_recipe, which an agent needs in order to route correctly in a 20-tool catalog.

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 goes further by enumerating the nine valid slugs (rag-assistant, voice-agent, ai-chatbot, support-agent, research-agent, telegram-ai-bot, data-analyst-agent, solana-bot, prompt-to-video), effectively supplying an enum the schema lacks and clarifying that fuzzy words like "voice agent" map to a slug.

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 concrete framing ("the parts for one kind of AI product") and then enumerates exactly what a recipe returns: APIs per part, model per price tier, libraries, skills, coding agents, startup cost and an AGENTS.md brief. That is far more specific than the title alone. It stops short of naming the sibling it differs from (list_recipes, design_recipe), so an agent must infer the boundary itself.

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 gives one explicit usage rule — "Call with no arguments to list them" — which is genuinely actionable for discovery. But with three related siblings (list_recipes, design_recipe, plan_project) present, there is no statement of when to pick this tool over them, and no guidance on what happens with an unknown slug.

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=false, so the safety profile is covered. The description adds genuine behavioral context by disclosing data provenance (public GitHub repos set up for AI coding agents), which tells the agent the results are static observations rather than live queries. It does not address freshness, caching, or result size.

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 dense sentence that front-loads the source and then enumerates content dimensions; nothing is wasted. It is slightly run-on, packing agent-level, combination, and per-domain scope into one clause chain, but it stays readable.

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 return-value burden and does so reasonably, enumerating the result categories (servers, combinations, per-domain APIs/SDKs/packages). Combined with 100% schema coverage on inputs and the readOnly annotation, an agent has enough to call it correctly; only freshness and output shape remain unstated.

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 both optional parameters (agent, domain) are already documented with their allowed values. The description adds domain-usage framing ('what those projects use') and examples that roughly mirror the schema, but no format or interaction details beyond what the schema provides. Baseline 3 applies.

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 concretely states the dataset: MCP servers developers connect, common combinations, and per-domain APIs/SDKs/packages, sourced from public GitHub repos. It distinguishes itself from data-catalog siblings like find_apis or find_tools by framing the content as observed real-world usage rather than a directory. The verb is implicit (a retrieval), so it falls short of a crisp verb+resource.

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?

There is no explicit when-to-use guidance, no conditions, and no named alternative among the many overlapping siblings (find_apis, find_tools, find_skills, list_recipes). The phrase 'overall or per agent' hints at how to slice the data but does not tell the agent when this tool is the right choice versus a catalog tool.

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 mark this as a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds value beyond them by disclosing the visibility model (only editors read it, never published) and a privacy constraint about omitting keys and personal data. It does not explain duplicate-submission behavior, consistent with idempotentHint=false, but the visibility and privacy disclosure is the important part.

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, front-loaded with the action and its audience, then the privacy caveat. The triple example ('a command that failed, a version that did not install, a step that did not work') is mildly redundant but earns its place by scoping what counts as an issue.

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 three-parameter, no-output-schema submission tool, the description covers purpose, trigger, audience, and privacy constraints. What the caller sees after submitting is unstated, but with no output schema and a fire-and-forget editorial report that is a small gap.

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 all three parameters (text, recipe, version) are already documented in the schema, including the recipe-id format and draft- prefix. The description's mention of the brief's line and command output largely restates the schema's own text guidance, so it adds little beyond baseline.

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 (report/tell) and resource (problems in a kit's AGENTS.md), plus the exact failure modes in scope (failed command, version that did not install, broken step). Nothing in the sibling list overlaps with this action, so the agent can route to it unambiguously.

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 a clear triggering context: use it after building from a kit when something was wrong, missing, or out of date. It does not name alternatives or exclusions, but no sibling performs a comparable action, so the omission is minor.

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