Vocenya Site

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 genuinely useful context beyond that: the return is the full document rendered as Markdown, not a summary or metadata stub.

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, with the core action and the required input source both front-loaded. Every clause 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?

No output schema exists, yet the description specifies the return shape (full article as Markdown) and the input provenance, which is everything an agent needs for a single-parameter read 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 100% and the slug property already includes a concrete example format. The description only adds that the slug originates from search_articles, which is a routing hint rather than additional parameter semantics. 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 (get), resource (guide or article), scope (one, in full), and output format (Markdown). It also implicitly distinguishes itself from search_articles by requiring a slug.

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 tells the agent where the required input comes from ('Use a slug from search_articles'), which routes it correctly away from the search sibling. It does not state when-not to use it or what happens with an invalid slug, but the context is clear.

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 genuinely useful behavioral detail beyond that: the payload is Markdown and contains specific sections (why businesses miss calls, handled calls, sample script, captures, FAQs). It omits any note on size, truncation, or auth, so not 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?

A single sentence, front-loaded with verb+resource, with the content enumeration and the slug-provenance note both earning their place. No filler or 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 tool with no output schema, the description supplies everything needed: how to obtain the slug and what the returned Markdown contains. Nothing an agent needs to call 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 schema already gives slug examples ("dentists", "plumbers"), so the baseline is 3. The description adds real value by stating where a valid slug comes from (search_industries), which the schema does not say.

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 the full Vocenya page for one industry") and even enumerates the page's sections, which no sibling does. The phrase "one industry" plus the slug provenance cleanly separates it from search_industries, which only locates slugs.

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 tells the agent to "Use a slug from search_industries," which is real routing guidance to the correct sibling. It stops short of stating when not to use this tool or naming the parallel page-getters (get_article, get_service) as alternatives, so it is clear context without 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavioral context: the data mirrors the published pricing page and trial length uses 0 as the sentinel for 'no trial', which an agent could not infer from structured fields.

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 names the resource first, then the returned fields. It is dense but every clause carries information; a parenthetical field list is the only mild density tax.

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 parameters and no output schema, the description carries the burden of describing return contents and does so by enumerating the exact fields. Nothing an agent needs to decide whether to call this tool or interpret its result 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 takes zero parameters, so the baseline is 4 per the rubric. Schema coverage is 100% and there are no parameters for the description to disambiguate, leaving nothing to compensate for.

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 ('Get Vocenya's current plans') and enumerates exactly what is returned: monthly price, AI minutes, overage rate, phone numbers, features, add-ons and trial length. This is clearly distinguishable from siblings like get_industry, get_service and list_locations, which cover different resources.

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 tool name and the 'exactly as published on vocenya.com/pricing' framing, so an agent knows this is the pricing lookup. However, there is no explicit when-to-use statement, no mention of alternatives, and no guidance on whether pricing is a point-in-time snapshot vs. needing refresh.

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 new behavior: the return format is Markdown, and omitting the slug changes the result shape into a list of all product pages with short descriptions. It does not discuss pagination or size limits for the full-page fetch, but the dual-mode disclosure is substantive.

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, zero filler. The core action and return type come first, and the alternate empty-slug mode follows immediately. Nothing redundant is included.

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, so the description must carry the return-shape burden, and it does: full page as Markdown, or a list with short descriptions when slug is omitted. With a single optional enum parameter and safety already declared in annotations, nothing needed for 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% and the enum of 24 slugs is fully self-documenting, so the baseline is 3. The description goes beyond the schema by explaining that an empty slug is legal and switches the tool into list mode — a semantic the schema itself does not state, since the schema only describes slug as a page identifier.

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: retrieves the full Vocenya page for a product or solution, returned as Markdown. The resource ('product or solution page') is distinguishable in practice from siblings like get_article and get_industry, but the description never names or contrasts those siblings, so differentiation is left 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?

It gives one useful usage rule — leave the slug empty to list all product pages — which tells the agent how to switch into browse mode. However, it offers no guidance on when to prefer this tool over get_article, get_industry, or search_industries, so the agent must infer selection from the resource noun 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 is covered. The description adds real value by disclosing the returned fields and the fact that the dataset is limited to two focus areas despite US-wide service, which tells the agent to expect a small fixed result set.

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 substantive content front-loaded; the second sentence is mildly tangential context about US-wide service. No filler or 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?

There is no output schema, so the description correctly carries the burden of describing returns and does so by listing the fields. It omits ordering and whether the list is exhaustive/paginated, which is a minor gap for a small fixed list.

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 'state' parameter is fully documented with an enum in the schema. The description only tangentially supports it by naming New Jersey and New York City, so the 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 a specific verb and resource ('List the places Vocenya has local pages for') and enumerates the returned content (type, state, area codes, page URL). The resource is unambiguous against siblings like get_article or search_industries, though it never explicitly contrasts itself with them.

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 tool name and the fact that the scope is confined to NJ and NYC, but there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives. Adequate but leaves the agent to infer intent.

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 safety (readOnlyHint=true, openWorldHint=false). The description adds genuinely new behavioral detail: the return shape (slug, short answer, URL) and result ordering (newest first), which the agent cannot get from annotations or 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?

Two sentences, front-loaded with the purpose, examples and return format packed in without waste. Every clause 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?

For a simple one-parameter read tool with no output schema, the description adequately covers purpose, return values and ordering. Minor gap: no mention of pagination or result-count limits, though likely not critical here.

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 baseline is 3. The description goes further by giving example query values and clarifying that an empty query is valid and means 'list all', adding meaning beyond the schema's maxLength/description.

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 (guides and articles) and grounds it with concrete example queries. It is clearly distinguishable from siblings like get_article (retrieval by slug) and search_industries (different domain).

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?

Explains the empty-query fallback ('list every article') and implies a two-step flow by noting the returned slug feeds get_article. It gives clear context but stops short of explicitly stating when to prefer this over get_article or search_industries.

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 closed-corpus scope are covered. The description adds real value beyond that: what each match contains (slug, category, page URL) and that an empty query enumerates the whole corpus. It omits pagination/result-count behavior, which keeps it short of 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?

Three tight sentences, front-loaded with purpose, then return shape, then the empty-query rule. No filler and nothing that could be trimmed without losing 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?

For a single-optional-param, read-only search with no output schema, the description supplies the return fields and the empty-query behavior, which is most of what an agent needs. Only minor gaps remain (result limits/pagination, no explicit sibling exclusion) given the low complexity.

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 query parameter is well documented there, so baseline is 3. The description adds semantics the schema lacks: the empty-string behavior ('list every industry') and that matching is against name or description, making the parameter's intent clearer.

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') plus resource ('industries') and scopes it to Vocenya's AI receptionist pages, with concrete examples ('dentist', 'plumber', 'auto repair'). The return contract (slug, category, page URL) and the link to get_industry clearly separate it from the sibling that fetches a single industry.

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 covers the empty-query case ('Leave the query empty to list every industry') and hints at the follow-up flow by naming get_industry as the consumer of the returned slug. It does not state when to prefer search_articles or get_industry instead, so no full when-not guidance.

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