Read-only VibeRaven guides: explain a finding, search launch guides, get a Supabase checklist.
Scored across 3 tools
Each tool has a fairly distinct purpose: explaining a finding id, returning a stack-specific checklist, and keyword-searching guides. There is mild overlap between launch_checklist and search_guides (both surface viberaven.dev content), but the descriptions clearly separate manual checklists from keyword search results.
All three names use consistent snake_case verb_noun phrasing (explain_finding, launch_checklist, search_guides). The pattern is predictable and readable throughout.
Three tools is on the lean side, but appropriate for a narrow, read-only content/guides server. Each tool covers a distinct content surface with no obvious redundancy.
As a read-only guides server, no CRUD lifecycle is expected; it covers finding explanations, stack checklists, and keyword search over published pages. A 'list all guides' or 'list all findings' operation is a minor gap that search largely works around.
Use this when the user asks what a VibeRaven finding id means, for example rls_disabled or env_var_drift, or pastes a finding from a VibeRaven 1.6.12 report. Returns what the rule detects in repository files, why it matters, how to fix it and what it does not check, quoted from viberaven.dev with a source link for each part. It does not read the user's repository, database or Vercel project. Known ids: rls_disabled, rls_no_policies, rls_policy_allows_all_read, rls_policy_allows_all_write, security_definer_function_executable, pooler_port_mismatch, service_role_key_in_client_code, env_var_drift. An unknown id returns found: false and the list of known ids.
| Name | Required | Description | Default |
|---|---|---|---|
| gap_id | Yes | The finding id as printed by VibeRaven, for example rls_disabled. |
| Name | Required | Description |
|---|---|---|
| found | Yes | |
| gap_id | No | |
| detects | No | |
| named_on | No | |
| known_ids | No | |
| how_to_fix | No | |
| does_not_check | No | |
| why_it_matters | No | |
| viberaven_version | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive and closed-world, but the description adds meaningful scope the annotations cannot express: it never reads the user's repository, database or Vercel project, its content is quoted from viberaven.dev with a source link per part, and an unknown id returns found: false plus the list of known ids. That is exactly the behavioral detail needed to set expectations for a lookup 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?
Front-loaded with the trigger condition, then the return shape, then the negative scope and id list. Every sentence carries distinct information; nothing restates the title or name.
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, the description covers trigger, return content, non-capabilities, and error behavior. An output schema exists, so the brief return-value summary is supplementary rather than a gap, and nothing an agent needs to call this correctly 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 coverage is 100% and the single gap_id parameter is fully described, so the baseline is 3. The description goes further by enumerating the eight known ids, giving format examples, and specifying the unknown-id failure behavior, which meaningfully guides valid input selection.
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 (explain) and resource (a VibeRaven finding id) plus concrete example ids (rls_disabled, env_var_drift), so the agent knows exactly what this returns. It is clearly distinguishable from launch_checklist and search_guides, which are action and documentation-lookup tools respectively.
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 crisp trigger conditions: 'Use this when the user asks what a VibeRaven finding id means ... or pastes a finding from a report,' which covers the realistic invocation contexts. It does not, however, name siblings such as search_guides as the alternative for general VibeRaven questions, so routing is clear but not fully disambiguated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user wants a manual pre-launch checklist for a Lovable + Supabase app or a Next.js + Supabase app on Vercel. Returns the checklist published on viberaven.dev for that stack with its sources, and the one optional local VibeRaven step (npx -y viberaven@1.6.12 check), which is advice, not a gate. The items are manual checks the user does in their dashboards and code; this tool does not run any of them.
| Name | Required | Description | Default |
|---|---|---|---|
| stack | Yes | lovable-supabase for a Lovable app with Supabase, nextjs-supabase-vercel for a Next.js app with Supabase deployed on Vercel. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| items | Yes | |
| stack | Yes | |
| title | Yes | |
| sources | Yes | |
| short_answer | Yes | |
| optional_repo_check | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely new behavioral context: the content source (viberaven.dev) with sources attached, and the crucial clarification that the items are manual checks the user performs, with the local `npx ... check` step being advice rather than a gate.
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 invocation condition and each sentence carrying distinct information (when to use, what is returned, what the tool does not do). There is mild redundancy between the stack list in prose and the enum, but 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?
For a single-enum read-only lookup tool with an output schema and full annotation coverage, nothing material is missing: the trigger, the output content, the non-execution boundary, and the optional local step are all 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?
Schema description coverage is 100% and the single `stack` parameter is a fully enumerated field whose values are documented in the schema itself. The description restates the two stacks in prose but adds no syntax, format, or default detail 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?
The description states a specific verb and resource (returns a manual pre-launch checklist) and scopes it precisely to two named stacks ('Lovable + Supabase' and 'Next.js + Supabase on Vercel'). It also draws a sharp negative boundary ('this tool does not run any of them'), so an agent cannot confuse it with an execution tool or with the sibling search_guides/explain_finding tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It opens with an explicit trigger ('Use this when the user wants a manual pre-launch checklist for...'), which is clear context for invocation. It stops short of naming alternatives or when-not-to-use conditions, but the tight stack scoping effectively excludes off-target requests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this when the user has a launch question about an AI-built app on Vercel + Supabase, such as Supabase RLS, env vars on Vercel, a Stripe webhook after deploy or a client handoff. Searches the launch guides published on viberaven.dev by keyword and returns up to 5 matches, each with its title, URL and the short answer from the page. It only searches those published pages: it does not browse the web or read the user's project. No match returns an empty list.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A few keywords from the question, for example "supabase tables missing rls". |
| Name | Required | Description |
|---|---|---|
| results | Yes |
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 still adds real substance: a result cap of 5, the per-match fields returned, and the empty-list behavior on no match, which the annotations do not convey.
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 use condition, then results, then scope limits; every sentence adds a distinct constraint and none is redundant with the name or 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 single-parameter, read-only search with an output schema present, nothing an agent needs is missing: trigger, scope boundaries, result count, per-item fields, and failure behavior are all stated.
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 single query parameter is fully documented in the schema with an example, so the description carries no extra burden. The phrase 'by keyword' is consistent with the schema but adds no syntax or format detail beyond it, matching the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb (searches) and resource (launch guides published on viberaven.dev), plus the precise return shape (up to 5 matches with title, URL, short answer). It also bounds scope by stating what is not searched, so an agent can distinguish this from a general web or project-introspection tool.
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 a clear trigger condition ('when the user has a launch question about an AI-built app on Vercel + Supabase') and gives concrete example topics, plus explicit exclusions ('does not browse the web or read the user's project'). It stops short of naming the sibling tools (explain_finding, launch_checklist) to route between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
explain_findinglaunch_checklistsearch_guidesRead-only access to the My AI Guide directory of AI tools, repos, plugins, news and guides.
Public read-only Orca guide: product, pricing, docs, and signup links.
Read-only search over the Founder Ventures library on bootstrapped SaaS, plus founder events.
Docs Q&A: search 169 data and AI guides, fetch any page as markdown. Read-only, keyless.
Add one secure layer between your agents and this server.