Vaeo AI Discovery Reports

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 - it is a cached, zero-cost read that does not trigger new AI work - but says nothing about return shape, size, or failure modes for a missing/expired order_key.

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 core purpose before the topic enumeration. The dense parenthetical topic list earns its space by defining enum values, though it is slightly cluttered.

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 read-only retrieval tool with annotations carrying the safety profile, the main gap is the absence of any output schema or description of what a returned section looks like, plus no mention of error behavior when the order_key is invalid. Adequate but not complete.

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 topic enum is undocumented in the schema, but the description compensates by glossing every value (e.g., 'who_the_ais_named (who is named more)', 'pages_the_ais_read (which sites to get on)', 'start_here (what to do first)'). The order_key relies on the schema's own description ('the order_key that order_report gave'), so coverage is adequate overall.

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 makes clear this retrieves a single section of an already-finished report from saved results, and explicitly negates the misleading verb in its own name ('no new AI questions'). It implicitly distinguishes from get_report (full report) and order_report, though it never names those siblings directly.

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 'from the saved results (no new AI questions, no cost)' signals the context for choosing this over a live-query tool, and the topic list implies what each call returns. However, it never states when to prefer this over get_report or how it relates to the other report tools, leaving routing 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully enumerates the possible order states, which helps interpret a result in the absence of an output schema, but it discloses nothing about polling/freshness behavior or whether the call requires prior payment context.

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 compact sentence with no filler, and the state list is front-loaded. It is arguably terse to the point of being a fragment rather than a full statement of purpose, which keeps it below a 5.

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 helps by listing the terminal/transient states an order can be in. Missing is any statement of the return shape (e.g., a single status value), the call's relationship to order_report, and any precondition, leaving it adequate but incomplete.

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 sole parameter's description ('The order_key that order_report gave') already documents its origin. The tool description adds no additional meaning about the parameter, so the baseline of 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?

The fragment 'Where an order is' implies a status-inquiry tool, and the enumerated states clarify the kind of result returned. However, there is no explicit verb+resource statement (the verb lives only in the name/title) and no differentiation from sibling reporting tools like order_report or get_report, so an agent must infer the purpose.

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?

There is no when-to-use guidance, no exclusion of alternatives, and no mention of the relationship to order_report even though the parameter schema references it. The agent gets no signal about when this tool is preferred over the report-oriented siblings.

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 and openWorldHint, so the safety profile is covered. The description adds real context beyond them: the data source (Google Maps), the geographic restriction (Australian businesses only), and the key returned artifact (each match's place_id).

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 sentences with zero filler; the action and scope come first and the downstream value of place_id is attached as justification. 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?

For a single-parameter lookup with no output schema, the description supplies the essential missing pieces: geographic constraint, the primary return value (place_id), and downstream tools. It does not mention behavior on ambiguous or no-match results, a minor remaining 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 coverage is 100% and there is only one parameter, so the schema carries the definition. The description's example ('Corner Dental Newtown') usefully demonstrates the expected query format of business name plus suburb, adding marginal value over the schema's terse 'Business name and suburb.'

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 ('Search Google Maps for an Australian business by name and suburb') plus a concrete example query, so the agent knows exactly what the tool does. It is clearly distinguishable from siblings like get_questions and order_report, which it names as downstream consumers rather than peer lookups.

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?

Tells the agent the situation this tool serves: obtaining a place_id that feeds get_questions and order_report, which routes the agent through the correct pipeline. It does not state any exclusions or what to do when no match is found, so it stops short of full when/when-not guidance.

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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful payload context (the questions asked of AIs, price expressed in A$) but says nothing about auth, error behaviour, or what happens if trade is omitted or invalid.

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 sentence is appropriately short, but the phrasing 'our trade for it' is cryptic and not front-loaded around an action verb. It is compact without being clear.

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 2-param read-only tool with no output schema, the description does convey what comes back, which is the main gap it needed to fill. It still leaves routing versus get_report and the trade-fallback behaviour entirely to the schema.

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 parameters are already documented in the schema, including the trade fallback to list_trades. The description's 'our trade for it' and 'for one business' loosely map to the params but add no syntax or constraint 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 lists the payload contents (business details, trade, report questions, price) for one business, but never states the verb clearly and the name 'get_questions' undersells what is actually returned. An agent could confuse this with get_report, and the description does nothing to distinguish 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?

No when-to-use guidance, no prerequisites beyond the schema's own 'From find_business' note, and no mention of how this differs from get_report or ask_about_report. The agent must infer the routing itself.

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 by structured data. The description adds real value by enumerating what the returned payload contains, but says nothing about what happens when the report is not yet finished, nor about error behavior for an unknown order_key. With annotations present, a 3 is appropriate.

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 'The finished report as data', with the long enumeration compressed into a readable list. It is dense but every clause maps to an actual part of the payload, so 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?

With no output schema, the description does the important work of describing return contents, which is a genuine strength and would otherwise be missing. However, it omits the precondition that the report must be finished and any failure mode, leaving the lifecycle around order_report/check_order unexplained.

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 schema already explains order_key as 'The order_key that order_report gave.' The description never references the parameter at all, so it adds nothing beyond the schema baseline of 3.

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 is a noun phrase enumerating the report's contents ('The finished report as data: how often the AIs named the business...'), which conveys the resource but never states an explicit retrieval verb. It also does nothing to distinguish itself from ask_about_report or get_questions, which target the same report domain. Purpose is inferable but not sharply defined.

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?

There is no guidance on when to call this versus ask_about_report, and no mention of the workflow implied by siblings order_report and check_order (i.e., that a finished order is a prerequisite). The word 'finished' hints at a readiness condition but the agent is left to infer it.

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 safe read-only nature is covered. The description adds a domain constraint about ordering eligibility, but does not describe return format, authentication needs, or other behavioral traits beyond what the annotations provide.

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 no wasted words. The first sentence defines the resource and the second adds a constraint, both front-loaded and easy to scan.

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 zero-parameter tool with no output schema, the description should explain what is returned. It conceptually says 'kinds of business' but does not specify whether the return is a list of names, IDs, or objects, nor how those values should be used with order_report. It is minimally adequate but leaves an important 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?

The tool has zero parameters, so per the rubric the baseline is 4. There are no parameter semantics to clarify, and the description appropriately does not invent any.

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 conveys the resource ('kinds of business Vaeo makes reports for') but uses a noun phrase instead of a clear verb and does not resolve the mismatch between the tool name 'list_trades' and the phrase 'kinds of business.' An agent can infer it returns a set of valid reportable business types, but the purpose is not stated as precisely as it could be.

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 sentence 'A business of another kind cannot be ordered yet' implies that this tool should be used to determine which businesses can be ordered for, but it does not explicitly say when to call it or name alternatives such as order_report. The constraint provides useful context but leaves routing 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 write (readOnlyHint=false), non-idempotent, non-destructive, open-world. The description adds genuinely new behavioral context beyond that: no charge occurs at order time, payment happens on Stripe's page, delivery is by email, and the order_key is the tracking handle. It doesn't cover link expiry or retry/idempotency behavior, 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?

Purpose and the no-charge guarantee are front-loaded, and every sentence carries operational content (what to give the user, what to retain, what compare mode yields). The telegraphic style ('Give the person the link and the price.') is efficient but slightly fragmented, keeping it short of a 5.

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-value burden and does so: payment link, price, order_key. For a 4-parameter ordering tool with two required inputs sourced from sibling tools, this is nearly complete, missing only failure/link-expiry behavior and a pointer that place_id comes from find_business.

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 75%, so place_id and trade rely on the schema/related tools. The description meaningfully enriches compare_with_place_id, explaining it must be a business of the same trade in the same suburb and that it produces two reports plus a comparison — information the schema's one-line description does not convey.

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 concrete verb+resource ('Start an order') and its immediate output ('get a Stripe payment link'), then traces the full lifecycle through payment to email delivery. This is clearly distinguishable from siblings like get_report and check_order without opening either schema.

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 through the workflow ('Give the person the link and the price', 'Keep the order_key to follow the order'), which tells the agent what to do with the result. However, it never names an alternative tool or states when this should not be used (e.g., when a report already exists, use get_report; to poll status, use check_order).

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