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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses the output format (full page as Markdown) and that the empty-slug path returns a different, abbreviated shape — useful context the annotations do not carry.

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, no filler. The primary mode is front-loaded and the edge-case mode (empty slug) follows immediately after.

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-parameter read tool with no output schema, the description covers what is returned (Markdown page), the alternate mode (listing with short descriptions), and the trigger for it. Nothing an agent needs in order 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 enum documents all 17 valid slugs, so the schema does most of the work. The description still adds value by explaining the omitted-slug behavior, which is not representable in the enum (the empty value isn't a listed enum member).

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 and resource ('Get the full Vocenya page for a product or solution') and names the return format (Markdown). It implicitly separates itself from get_article and get_industry by specifying product/solution pages, but it never names those siblings 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?

It clearly documents the second mode of use: leaving the slug empty lists every product page with a short description, which is a genuine when-to-use signal an agent cannot infer. It does not, however, route the agent away from alternatives like get_article or search_articles when those are 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=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.