VibeHacker

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the safety profile is covered without the description. The description adds the scoping detail that the fetch is by a single slug, which is slightly more context than the annotations provide, but it does not disclose anything about return format, error behavior, or authentication.

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 description is six words and contains no filler; every word contributes. It is also front-loaded with the core action and object.

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 fetch-by-slug tool with strong annotations, the description is largely adequate: an agent can identify the required input and understand the operation is a read. The lack of any guidance on return shape or error conditions is a minor gap, and the presence of a preview_tool sibling leaves some ambiguity about when this is the right choice, but the core calling contract is clear.

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 only one parameter, and the description explicitly explains that slug is the identifier used to fetch the tool, which adds meaning beyond the schema's bare string type and minLength. This is sufficient for a single-parameter get operation.

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 ('Get'), a specific resource ('one tool'), and the lookup key ('by slug'), so an agent can tell this is a singular fetch-by-identifier operation. It is clear on its face, though it doesn't explicitly call out how it differs from preview_tool or search_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?

The description implies the use case: call this when you know a tool's slug and need the full tool record. However, it gives no explicit guidance about when to prefer this over search_tools or preview_tool, and no exclusions are stated.

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 with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds one useful behavioral detail—the list includes tool counts—but does not describe other aspects like ordering or pagination. No contradiction with 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?

The description is one short, front-loaded sentence: verb first, then resource, then the key output detail. Every word earns its place and there is no redundancy.

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 parameterless, read-only listing tool, the description covers the essential information: what it lists and what the output includes. The annotations provide the safety context, and no output schema is needed given the simple return described. Nothing critical 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?

The tool has zero parameters and schema description coverage is 100%, so the description has no parameter meaning to add. The baseline of 4 applies because there is nothing missing.

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 'List' and resource 'categories', and clarifies the output includes 'tool counts'. It is clearly distinct from sibling tools like get_tool and search_tools, but it does not explicitly name alternatives or draw contrasts, 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?

The description implies the use case — call this when you need a list of categories — but gives no explicit guidance on when to prefer it over alternatives or any exclusion conditions. Simple context, but no direct 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a practical prerequisite, 'Requires a token,' which is useful auth context beyond the annotations. It does not discuss pagination or response shape, but for a simple zero-parameter list tool that is not a major gap.

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 description is two short, purposeful sentences with no filler. The primary action and scope are front-loaded, and the token requirement is stated as a clean, separate note.

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 zero-parameter, read-only listing tool, the description provides the action, the resource scope, the returned information ('review status'), and an auth prerequisite. No output schema exists, but the description sufficiently conveys what the agent should expect at a high level.

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

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

The tool has zero parameters, so the description does not need to explain parameter syntax or semantics. The schema coverage is effectively complete, and the description's focus on 'tools you submitted' gives the agent enough to understand the implicit scope of the call.

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 ('List') and a clearly scoped resource ('the tools you submitted'), and adds 'review status' as the information returned. This immediately distinguishes it from sibling tools like submit_tool, search_tools, and get_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?

The use case is clear: this tool is for retrieving the agent's own submissions and their review status. It does not explicitly compare itself to siblings or state when not to use it, but the scope is specific enough that an agent should recognize when it applies.

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 behavior. The description adds a useful auth requirement ('Requires a token') and reinforces that no submission occurs. It does not describe output behavior, but this is partially mitigated by the aligned 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?

The description is two short sentences with no filler. The core purpose is front-loaded, and the token requirement is a necessary invocation detail that 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?

Given the single required parameter and rich annotations, the description is mostly adequate, but it leaves gaps: it does not state what the tool returns, how the token is provided, or clarify that 'draft' means generating a preview rather than persisting anything.

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%, and the description does not mention the `url` parameter or its relationship to the preview action. The schema only provides type and format, so the description should compensate by explaining the parameter's role, but it 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 ('draft') and resource ('listing'), and the phrase 'without submitting it' directly distinguishes this from submit_tool. However, 'draft' is slightly ambiguous relative to the title 'Preview a listing', and the actual preview behavior is only implied rather than 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?

The phrase 'without submitting it' implies this tool is for pre-submission previews and implicitly contrasts with submit_tool, but the description does not explicitly state when to use this tool versus alternatives or mention any exclusion conditions.

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 destructiveHint false, so the safety profile is covered. The description adds that only published tools are searched and which fields are matched, but it does not disclose result ordering, pagination, or category-filter behavior beyond the schema.

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: verb, resource, and search scope. Exactly as concise as a search-tool definition 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?

For a simple read-only search tool, the definition plus schema and annotations are sufficient to select and invoke it. The only minor gap is the absence of an explicit return shape, but no output schema exists and the action implies a list of matches.

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 low (only category has a description), but the description explains that query matches name/tagline/maker. limit and category are inferable from schema constraints and category's description, though the interaction between query and category is not stated.

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 ('published tools') plus the searchable attributes (name, tagline, maker). This clearly distinguishes it from get_tool for direct retrieval and list_categories for category browsing.

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 use when the agent wants to find tools by free-text search, but it does not explicitly say when to prefer get_tool or list_categories, nor any exclusions. Context is clear but alternative-selection guidance is absent.

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 indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds concrete behavioral context: it reads the site, drafts the listing, requires a token, and returns an existing listing instead of creating duplicates, which gives the agent useful real-world behavior beyond 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?

The description is compact and well-structured: three sentences, each earning its place by covering the main action, the auth prerequisite, and idempotent behavior. No filler or redundant restating of the tool 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 relatively simple tool with three parameters and no output schema, the description covers the core workflow, auth requirement, and duplicate handling. It does not specify the exact return value for a new submission or the token source, but it gives enough context for an agent to select and invoke the tool appropriately.

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 does not add meaningful parameter-level detail beyond what the schema already provides, although 'Submit a website' maps naturally to the required url parameter and 'drafts the listing' hints at how the input is used.

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 the action: 'Submit a website to VibeHacker', then details the workflow of reading the site, drafting the listing, and filing for review. This distinguishes it from sibling tools like preview_tool, search_tools, and upvote_tool by describing a unique submission workflow.

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 intended use is implied clearly—submit a website when you want it listed on VibeHacker—and the token requirement is a useful prerequisite. However, it does not explicitly mention alternatives or when NOT to use this tool, such as using preview_tool for drafting or my_submissions for checking existing submissions, so usage guidance vs siblings is incomplete.

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?

With all annotations false, the description carries the burden of explaining behavior. It adds two useful facts: 'Toggle' reveals non-idempotent mutating behavior, and 'Requires a token' warns about authentication demands. It does not contradict 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?

Two short sentences, each earning its place: the first states the core action, and the second states the required prerequisite. There is no redundant or filler 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 single-parameter toggle operation, the description covers the main behavior, auth requirement, and object of the action. It could mention return values or edge cases, but the low complexity and lack of output schema make this acceptable.

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 only parameter, slug, is fully documented in the schema with an example (claude-code), so schema coverage is 100%. The description adds no additional parameter detail, but the baseline of 3 applies because the schema already 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?

The description states a specific verb ('Toggle') and a clear resource ('your upvote on a tool'). This clearly distinguishes it from siblings like get_tool or submit_tool, which involve reading or submitting content rather than voting.

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 gives a practical prerequisite ('Requires a token') and the action itself communicates when to use it. However, it does not explicitly describe when to use this tool versus alternatives or provide any exclusions, so usage guidance is only implied.

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