Vibe Shipped

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so safety is covered. The description adds useful behavioral context by disclosing the information returned (pricing, licence, features) and that it is sourced, which the annotations do not convey. It stops short of saying what happens for unknown tools or how sources are cited.

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?

Three short sentences, front-loaded with the trigger condition and immediately followed by the return content. The trailing example largely duplicates the schema's example text, so the last sentence earns little of its space.

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 tool is simple (one array parameter, no output schema, low-risk read), and the description covers the trigger, the data returned and a usage example. Only marginal gaps remain: the 4-tool ceiling lives solely in the schema and unknown-slug behavior is 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% and the schema already documents slug format with examples plus the 2-4 item bounds. The inline example in the description repeats the schema's own example, adding no new semantics such as slug resolution behavior or error handling for unrecognized tools.

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 (compare) and resource (AI coding tools/app builders/agents) and states what the output contains: sourced pricing, licence and features side by side. It is clearly distinguishable from find_tool_for_task or get_tool by virtue of the side-by-side comparison framing, though no sibling is named 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?

"Use when the user asks to compare AI coding tools, app builders or agents ('X vs Y')" gives a concrete trigger condition. There is no when-not guidance and no explicit pointer to alternatives like recommend_stack or find_tool_for_task for non-comparison lookups.

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 readOnly, idempotent, non-destructive, and non-open-world, so the safety profile is covered. The description adds value beyond that by disclosing the result contract: exactly three 'verified working' options, an install snippet, and a payload budget of roughly 3 KB, which tells the agent the response is deliberately small and pre-validated.

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?

Three compact sentences, front-loaded with the capability, then the return contract, then a concrete example. 'Find or search for' is mildly redundant, and the parenthetical service list overlaps with the schema's examples, 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?

All six parameters are optional and fully documented in the schema, and no output schema exists, so the description carries the burden of describing returns — which it does by naming the top-3 verified options, the one-line install, and the size ceiling. The remaining gap is the lack of any routing guidance toward the many sibling 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 description coverage is 100%, so the baseline is 3. The description only lightly reinforces parameters — 'top 3' maps to the default limit, and 'about 3 KB' versus full records hints at the verbose/fields tradeoff — but it never explains limit, fields, client, or industry beyond what the schema already says.

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 (find/search) and a specific resource class (MCP server, connector, integration, agent, skill) plus the use case framing 'for a task'. It also previews the result shape — top 3 verified working options with a one-line install — so the agent knows exactly what it gets back, and an inline example anchors the pattern.

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 implied by the 'for a task' framing and the sample tasks (query Postgres, automate a browser, take payments, send email), which show the right granularity of query. However, no alternatives are named: siblings like search_apps, get_tool, or compare_tools are never mentioned, so the agent must infer when this differs from a plain app search.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine context beyond that: it discloses the returned payload (source, stack, stated revenue) and that the input slug should originate from search_apps. It does not cover behavior for an unknown slug, 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 short sentences, zero filler. The usage condition and payload are front-loaded before the optional example, so an agent gets the decision-relevant information first.

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-parameter read tool with no output schema, the description covers trigger, prerequisite, and the main return fields. Only edge behavior (unknown slug, empty result) is unaddressed, which is a minor 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% – the slug parameter is fully documented with its own example ("stella"). The description's only added semantic is provenance ("from search_apps"), which is useful but minimal, 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?

States the resource (app, identified by slug) and exactly what the caller gets back: source, stack and stated revenue. This clearly differentiates it from search_apps (which finds slugs) and from get_tool/compare_tools, so an agent can tell which sibling to pick 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?

"Use when you have an app slug from search_apps and need its source, stack and stated revenue" gives an explicit trigger condition and a prerequisite chain (call search_apps first). There is no explicit when-not or negative case, so it falls just short of a full 5.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the 'current' freshness implication — it says nothing about caching, staleness, or what happens when a slug isn't found.

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 short sentences with the usage condition front-loaded, followed by a callable example. Zero filler; every element 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?

For a simple one-parameter read tool with no output schema and full annotation coverage, the description is nearly complete. It tells the agent what domain of data comes back ('pricing or facts'), though it could hint at the response shape or missing-slug 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% and the slug parameter already carries examples in the schema. The description's example {"slug":"cursor"} mirrors the schema rather than adding new meaning, so baseline 3 is appropriate for a single fully-documented parameter.

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 ('facts for one AI coding tool or agent harness by slug') and gives concrete slug examples. This scope (single tool, keyed by slug) implicitly separates it from siblings like compare_tools, find_tool_for_task, and get_tool_trends, though none are named 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?

'Use when you need current pricing or facts' gives a clear triggering condition, which is better than nothing. However it names no exclusions and does not route to alternatives such as compare_tools or find_tool_for_task, leaving the agent to infer when a different sibling is more appropriate.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — 'Live nightly-probe counts', i.e. data freshness — but says nothing about result ordering, sizes, or failure behavior beyond what the schema implies.

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?

Three short sentences, front-loaded with the use case, then the data-freshness note, then the call examples. No filler and nothing redundant with the schema.

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 eight enum sections and no output schema, the description never explains what 'summary', 'compare', or 'demand' actually return, which is the main ambiguity an agent faces here. The annotation and schema coverage make it callable, but not fully self-explanatory.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by stating 'No arguments needed' and showing '{}' versus '{"section":"compare"}', which clarifies that defaults yield a usable result and demonstrates how to target a section.

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 purpose — surfacing which MCP servers are most reliable, biggest, or best in given categories — backed by the title 'Top MCP servers: live reliability and size'. It is clear what the tool produces, but it never explicitly contrasts itself with siblings like compare_tools or find_tool_for_task, so an agent must infer the boundary.

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 opening 'Use when asked which MCP servers are most reliable, biggest, or best for Postgres, payments, browser or GitHub' gives explicit trigger conditions with concrete example domains. It does not name when NOT to use it or point at an alternative sibling, so it stops short of a 5.

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, idempotentHint and non-destructive, so safety needs no restating. The description adds value beyond them by disclosing what comes back — ranked picks with pricing and real example apps — which matters because no output schema exists.

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?

Three sentences, front-loaded with the use trigger, followed by the return contract and a compact example call. Every sentence earns its place and nothing is repeated from the schema.

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 six-parameter read-only recommendation tool with no output schema, the description covers purpose, return contents, and an example invocation. The only gap is that it never explains how the optional filters (platform, experience, budget, preferred_harness) influence ranking or whether they are hard constraints versus ranking signals.

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 every parameter including the enums, the limit bounds, and the budget_usd_month '0 = free tiers' semantics is already documented structurally. The description only echoes the idea parameter through its sample payload and adds no meaning beyond the schema, so the baseline 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 (recommend) and resource (AI coding tool / app builder) and names concrete candidates (Cursor, Claude Code, Lovable, Bolt, Replit, v0) so the agent knows the domain instantly. It also states the return shape (ranked picks with pricing and real example apps), which no sibling tool 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?

The trigger is explicit: use when the user wants to build an app and asks which AI coding tool or app builder to use. It does not, however, contrast itself with nearby siblings like find_tool_for_task or compare_tools, so the agent must infer the boundary from names 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds only that results are 'real apps built with AI tools,' which usefully scopes the corpus, but says nothing about result ordering, pagination, or empty-result behavior for a search tool.

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 short, front-loaded sentences: trigger condition first, invocation example second. The example is somewhat redundant with the schema's own example values (q='fitness', tool='lovable'), which costs a little efficiency, but there is no 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?

All parameters are optional with a default limit of 10 and no output schema, so the description should at least hint at what a result is (a list of apps) and how many are returned by default. Those gaps are minor given full schema coverage and safety annotations, but they leave the agent guessing about response shape.

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 five parameters are already documented, including the AND-matching semantics of q and the fact that industry affects only anonymous stats. The description only mirrors those fields in prose plus a sample call, adding marginal meaning 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?

States a specific verb and resource — search apps built with AI tools — and names the facets it searches on (keyword, tool, category). It implicitly separates itself from get_app (single fetch) and find_tool_for_task (tool lookup), but never names a sibling to make the distinction explicit.

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?

Opens with an explicit trigger: 'Use when the user wants real apps built with AI tools.' That is clear context for invocation, but there are no exclusions or routing advice — e.g., nothing says when to use compare_tools, get_app, or find_tool_for_task 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?

Annotations already declare this is a non-read-only, open-world, non-idempotent write, so the safety profile is covered. The description adds the important implicit detail that the submission is about an app 'built with AI' and that a public proof post is part of the deal, but it says nothing about review, duplication, or what happens to the user's data after submission.

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 terse, front-loaded sentences with no filler. The embedded example earns its place, though it slightly blurs the boundary between required and optional fields since it omits any explanation of the payload shape.

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 six-parameter, open-world submission tool with no output schema, the description covers the trigger but leaves out what the caller should expect afterwards (queued, reviewed, published, deduplicated). Adequate to invoke, incomplete for setting user expectations.

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 every field is already documented, establishing a baseline of 3. The inline example helps show a minimal valid payload, but it only illustrates the three required fields and adds no semantics for tools, one_liner, or builder_name.

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 ('add their app ... to Vibe Shipped'), which is clearly a write/submission action distinct from the read-oriented siblings (get_app, search_apps, compare_tools). It could name the destination's nature (a public directory) more explicitly, but the intent 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 phrase 'Use only when the user asks to add their app built with AI' gives an explicit trigger condition plus a restriction ('only'), which is stronger guidance than most sibling tools likely receive. It doesn't name an alternative, but no sibling covers this action.

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, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The description adds only the fact that the call works with zero arguments; it says nothing about result ordering, recency window, or pagination behavior, which would matter for a 'what's new' feed.

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?

Three tight sentences, front-loaded with the usage trigger and ending with invocation examples. The sequence 'No arguments needed' followed by two example argument shapes is slightly at odds in tone but still informative rather than wasteful.

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

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

For a simple, read-only, zero-required-parameter feed tool with a fully documented schema and rich annotations, the description gives the agent enough to call it correctly. The absence of any hint about the returned fields or ordering is a minor gap given there is no 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 type, limit and since are fully documented in the schema and the baseline of 3 applies. The example {"since":"2026-10-20"} reinforces the date filter's format but adds nothing about the type filter or limit 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?

The description states a concrete purpose: surfacing what changed recently in AI coding tools, harnesses or apps. The resource scope is specific enough to separate it from catalog lookups like get_tool or search_apps, though it never names a sibling or contrasts with get_tool_trends, which could also answer 'what changed' questions.

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?

'Use when asked what changed recently in AI coding tools, harnesses or apps' gives an explicit triggering condition, and 'No arguments needed' tells the agent it can call immediately. There is no when-not guidance or named alternative for narrower lookups, which keeps it short of a 5.

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