VibeRaven Guides

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

Beyond the annotations (readOnly, idempotent, closed-world), the description discloses that it does not read the user's repository, database or Vercel project, that answers are quoted from viberaven.dev with source links, and that an unknown id returns found: false plus the known-ids list. That is meaningful behavioral context the annotations cannot 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?

Content is front-loaded with the trigger condition first, then return behavior, then exclusions, then the id list. The enumeration is long but functional; no sentence 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?

An output schema exists, so return details need not be repeated, and the description still covers trigger, scope limits, return shape, and error behavior. Nothing an agent needs to invoke it 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 parameter is documented there, so baseline is 3. The description adds value by enumerating the eight known ids and defining the failure mode for unknown ids, which the schema does not.

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 (explain) and resource (a VibeRaven finding id) and gives concrete examples (rls_disabled, env_var_drift). It is clearly distinct from the siblings launch_checklist and search_guides.

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 explicit triggering conditions: 'Use this when the user asks what a VibeRaven finding id means' or pastes a finding from a report. It does not name an alternative tool, but no close sibling performs this function, so the routing is unambiguous.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful context beyond them: results come from viberaven.dev with sources, only one optional local step is included, and the tool executes none of the checks. No contradiction with the annotations.

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 usage trigger, then what is returned, then the critical scope caveat that the checks are manual. No filler or redundant restatement of the 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?

An output schema already exists so return values need not be detailed, yet the description still names the result (checklist with sources) and the single optional step. For a one-parameter read-only tool, an agent has everything needed to call it 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% and the single enum parameter is fully self-describing, so the schema carries the load. The description restates the two supported stacks in natural language, which helps map a user request to an enum value, but adds no syntax or format 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?

The description states a specific verb and resource: it returns a manual pre-launch checklist, scoped to exactly two named stacks (Lovable + Supabase, Next.js + Supabase on Vercel). It is clearly distinguishable in kind from a guide search or a finding explanation, but it never names or explicitly contrasts with its 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?

It opens with an explicit trigger ('Use this when the user wants a manual pre-launch checklist...') and clarifies the boundaries: the items are manual, the local VibeRaven step is optional advice rather than a gate. It does not name an alternative tool (e.g. search_guides) for the case where the user wants something other than a checklist.

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 (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: a hard cap of 5 matches, the result shape, an empty list on no match, and explicit scope limits (only published pages, no web browsing, no project access).

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 scope, then return behavior, with no filler sentences. Slightly longer than strictly necessary in the scope clause, but every sentence 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?

An output schema exists, so return values need no elaboration, yet the description still usefully notes the 5-match cap and empty-list behavior. Combined with the safety annotations, an agent has everything needed to call this 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?

There is a single parameter with 100% schema coverage and a worked example already in the schema, so the description only echoes the 'by keyword' idea. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (searches) plus a precisely scoped resource (launch guides published on viberaven.dev), and draws the boundary against web browsing and project reading. An agent can distinguish it from explain_finding and launch_checklist immediately.

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 condition ('Use this when the user has a launch question about an AI-built app on Vercel + Supabase') backed by four concrete examples. It also states what the tool does not do, though it never names the sibling tools as alternatives.

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