KOB Live Restaurant Ops Audit

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so 'Read-only' is largely redundant. The real added value is the disclosure of return contents and the strict output-fidelity constraint ('Never invent hours, ratings, or revenue') plus the 'when available' caveat on Yelp, which tells the agent to expect missing-source handling rather than a hard failure.

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 with the core action front-loaded, followed by outputs, then the constraint. Nothing is padding except 'Read-only', which duplicates the readOnlyHint annotation. Efficient and skimmable.

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 output schema, the description usefully enumerates the return payload, and annotations cover safety. But a zero-required-parameter, openWorld tool never explains which identifier combinations actually drive a lookup (placeId vs location vs googleMapsUrl vs websiteUrl), leaving the agent to guess at a valid invocation.

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 57%, so several parameters (name, placeId, googleMapsUrl) carry no documentation anywhere. The description adds no parameter meaning at all: it does not explain how name/placeId/location/websiteUrl relate, which are sufficient to run an audit, or what 'when available' implies for websiteUrl overrides. This is a clear compensation gap.

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 (Compare) and enumerates the resources it reconciles: the public Google listing, the restaurant website, and Yelp. It also names the concrete artifacts produced (score, discrepancies, impact notes, data gaps), which distinguishes it from the single-source siblings get_google_listing and get_yelp_listing. It stops short of explicitly routing agents away from those siblings, so it is not 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 composite framing implies when the tool is appropriate (cross-source reconciliation rather than a single lookup), and the schema-level 'example' parameter implies a demo path. However, there is no explicit when-to-use, no when-not-to-use, and the sibling tools that fetch individual sources are never named as the alternative for narrower needs.

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?

Goes well beyond the annotations by disclosing the actual sink chain: POST JSON to LEAD_WEBHOOK_URL, fall back to emailing only the KOB inbox via Resend, and fall back again to server-side logging with the lead still returned. It also rules out side effects (no restaurant email, no Google mutation), which the openWorldHint=true annotation cannot express on its own.

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-loads the action and its precondition, then packs the sink/fallback behavior into tight conditional clauses. Dense but every sentence carries load; only the back-half fallback detail could arguably be trimmed.

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 9-parameter, non-idempotent, open-world write with no output schema, the description covers the important unknowns: what is transmitted, where it goes, what happens on each configuration fallback, and what is never done. It leaves return-value shape slightly vague ('the result still contains the lead') but that is a minor gap.

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 only 33% across 9 params, so the description must compensate and it only partly does: it explains that consent must be true and that auditSummary is a short, verified-findings-only summary. Fields like town, email, notes, placeId, website and restaurantName get no elaboration here, though the self-explanatory names carry most of the load.

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 ('Record a trial lead') plus the trigger condition, which is enough to distinguish it from every sibling (none of which touch leads). An agent can tell immediately this is the outbound lead-capture sink, not an audit or lookup 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?

Gives an explicit precondition ('after the user typed their details and asked to be contacted') and two exclusions ('Never email the restaurant. Does not change Google.'). It stops short of naming an alternative sibling to use instead, but for a terminal capture action there is no competing tool to route to.

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 readOnly/idempotent/non-destructive, and the description adds meaningful behavior beyond them: drafts are never posted, reviews with existing owner replies are skipped, and fabrication is explicitly forbidden. It does not mention auth requirements, rate limits, or what the returned drafts look like.

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?

Five short sentences, each carrying a distinct constraint, with purpose and the never-posted guarantee front-loaded. Nothing is repeated from the schema or the annotations.

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 no-required-param, no-output-schema tool the critical behavior (drafts not posted, no fabrication, skip already-replied) is covered. The remaining gap is which location identifier to supply when reviews come from Google, which neither the description nor the schema resolves.

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 50%. The description clarifies the dual source of the reviews parameter (user-pasted vs Google-returned), matching that param's schema text, but says nothing about the undocumented placeId, googleMapsUrl, or restaurantName fields, leaving the agent guessing how to target a restaurant.

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 (draft) and resource (owner replies to reviews), plus the two input sources: reviews the user pasted or that Google returned. No sibling tool touches reviews, so the agent can identify this tool immediately without conflict.

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 explicit exclusions — skip reviews that already have an owner reply and do not invent reviews — which tell the agent when not to act on a given review. It stops short of naming an alternative tool or stating the top-level triggering condition a user must satisfy.

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 readOnly, idempotent, openWorld and non-destructive, so the safety bar is low. The description still earns credit by adding two behavioral facts not in the annotations: it returns a candidate set rather than a single definitive match, and it explicitly refuses to fabricate a match when Google is unconfigured.

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 short sentences with no filler; the input modes come first and the behavioral caveat about not inventing matches is last. Every sentence carries distinct 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?

With no output schema, the description is expected to cover return behavior; 'Returns candidates' signals a list but does not describe the shape or count of candidates. Given five parameters and no required fields, the description omits how optional inputs combine, though the critical failure-mode behavior is covered.

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 parameter semantics are already documented and a 3 is the baseline. The description adds only a loose mapping to name/location/googleMapsUrl and says nothing about the 'client' or 'example' parameters, leaving the 'plus' phrasing ambiguous about whether name and location are jointly required.

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 ('find a public restaurant listing') and names the two input modes it accepts. It does not explicitly distinguish itself from siblings like get_google_listing or get_yelp_listing, which an agent would have to infer.

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 when the tool applies by spelling out its input shapes (name + town/postcode, or a Google Maps URL), but it gives no explicit guidance on when to prefer it over get_google_listing or get_yelp_listing, nor any 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the trailing 'Read-only' is largely redundant. The one genuine addition is 'when the Places API returns them', which warns that fields may be conditionally absent — useful, but thin for a live external API call.

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 tight, front-loaded sentences with the verb and resource first and the returned fields enumerated compactly. The only wasted phrase is 'Read-only', which duplicates the annotation.

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 output schema, the description usefully enumerates the returned fields, which is appropriate. However, it omits the crucial input story (placeId vs googleMapsUrl, whether either is required) and gives no signal on how to disambiguate from the Yelp sibling.

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 only 50%, with placeId and googleMapsUrl completely undocumented in both schema and description. The description never explains that these are alternative place identifiers, whether one is required, or how they interact — a real gap for a lookup tool whose core parameter semantics are unstated.

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 ('Fetch') and resource ('public Google place details') and enumerates the returned fields (hours, phone, website, rating, review count, reviews), so an agent knows exactly what it produces. It does not explicitly contrast with the sibling get_yelp_listing, leaving source differentiation to the tool name alone.

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?

No when-to-use guidance and no alternatives are named, despite get_yelp_listing and find_restaurant being obvious siblings. The agent must infer that this is the Google-source lookup tool from the name only; nothing states when to prefer it or how it differs from the Yelp variant.

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, open-world), but the description adds real behavioral context beyond them: robots.txt is respected, page text is untrusted (a prompt-injection warning), and unparseable hours must be reported rather than fabricated. It does not mention rate limits, caching, or failure modes for unreachable sites.

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?

Four short sentences, front-loaded with the core action and followed by the two grounding constraints. 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?

With no output schema, the description carries the return-shape burden and does name the parsed fields, plus gives an explicit fallback behavior when parsing fails. Minor gap: it does not describe the shape of the response or what happens on network/robots.txt refusal.

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 both url and the example flag are fully documented in the schema, including the fixture-toggle behavior. The description adds no parameter-level meaning beyond that, 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?

States a specific verb and resource (fetch the restaurant's public website) plus the exact artifacts extracted (hours, phone numbers, menu links). This clearly separates it from get_google_listing/get_yelp_listing, which serve the same restaurant data from different sources.

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 extracted fields rather than stated: an agent infers this is the tool for hours/phone/menu from the restaurant's own site. It never names get_google_listing or get_yelp_listing as alternatives or says when the website is preferable to a listing API, so the routing decision is left to inference.

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 read-only/idempotent/open-world safety, and the description adds meaningful behavior on top: the API-key dependency, the failure mode when no close name match is returned, and an explicit anti-hallucination instruction. It does not describe return shape or rate limits, but the added context is genuine.

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?

Four short sentences, all front-loaded and free of padding. The staccato list of caveats reads slightly like a policy dump rather than a description, but nothing is wasted.

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 and none is needed for a read-only lookup, and the description covers the key failure modes. But with a four-parameter schema at 25% coverage and no explanation of how the identifiers interact, an agent still lacks enough to invoke it confidently in ambiguous cases.

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 only 25% (just the 'example' fixture flag), yet the description explains none of name, yelpUrl, or location or how they relate (e.g., is yelpUrl an alternative to name+location?). With three of four parameters undocumented, the description fails to compensate for the coverage gap.

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?

Specific verb ('Fetch') plus resource ('a Yelp Fusion business'), and it explicitly scopes out TripAdvisor, which helps separate it from get_google_listing and get_website_profile among the siblings. It stops short of naming the sibling tools it competes with, so it is clear but not maximally differentiated.

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 a precondition (YELP_API_KEY must be set) and a fallback ('If the key is missing ... say so'), which is real usage context. However it never says when to prefer this over get_google_listing or find_restaurant, so the alternative-selection 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.