Advisors AI — Route a Store Need to a Service

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing the safety profile. The description adds the boundary that it does not determine eligibility or order, and lists content categories. It does not provide deeper behavioral detail, but the output schema covers return structure.

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 sentences with no filler. The usage trigger is front-loaded, and the negative boundary is a single short sentence. 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 simple read-only lookup with a rich schema and an output schema, the description covers when to use it, what content it returns, and the key exclusion. The prerequisite to first identify a service is implied but not stated as an explicit call to the list tool, which 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 100%: both service_id and language have clear descriptions, including the enum source and default. The description adds no extra parameter meaning beyond what the schema already gives, so the baseline of 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?

The description states a specific verb ('get') and resource ('one public service and its packages'), and enumerates the returned content: scope, limits, commercial packages, sample, and terms. It partially distinguishes from siblings through 'Does not determine eligibility or order', but does not name alternative tools 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 explicitly conditions use on 'after a service is identified' and the user needing published service details. It also gives a clear when-not-to-use boundary: 'Does not determine eligibility or order.' However, it fails to name the exact alternative sibling tools, leaving some 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 establish readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail by specifying the exact output count ('exactly five public services') and by constraining when the tool should not be used. This goes beyond what annotations alone convey.

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 primary use case front-loaded and the negative constraint placed second. There is no redundant explanation, and every word contributes to selection or invocation decisions.

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?

The tool is simple: one optional language parameter, full schema documentation, an output schema, and extensive annotations. The description supplies the missing selection context and the exact service count. Nothing an agent needs to call this tool correctly is absent.

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 single language parameter is fully documented with an enum and default value. The description does not add parameter-level detail, but this is acceptable because the schema carries the semantic burden completely.

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 uses a specific verb ('list') and resource ('five public services'), and clarifies scope by stating it returns exactly five public services. It also distinguishes itself from fit/order-related tools via explicit do-not-use instructions, making it clearly separable from siblings.

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 an explicit trigger condition: 'Use when a user asks what Advisors AI offers.' It also states when not to use the tool ('do not use it to infer fit or to create an order'). However, it does not explicitly name the alternative tools, though sibling names like advisors_catalog_match_service and advisors_order_prepare_link make the alternatives inferable.

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 read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: results are deterministic, at most two suggestions, and not a diagnosis or proof of fit. This prevents the agent from overinterpreting the output.

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 with no filler. The trigger condition is front-loaded, and the determinism, result count, and epistemic limitations are conveyed in a compact, readable way.

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?

The output schema documents return values, annotations cover the safety profile, and the description covers the trigger, the output limit, and the interpretation caveat. Nothing essential is missing for an agent to select and invoke the tool correctly.

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 schema fully documents the 'need' and 'language' parameters, including the privacy warning for 'need'. The description reinforces that 'need' is a business need but adds little beyond the schema's own parameter descriptions.

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 title and description clearly identify a routing/matching action: it takes a business need and returns up to two service suggestions. The 'has not chosen a service' qualifier differentiates it from get/list siblings, and the disclaimer 'not a diagnosis or proof of fit' further clarifies its scope.

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 opens with an explicit trigger condition: use when the user describes a business need but has not chosen a service. It does not name sibling alternatives or give when-not-to-use exclusions, but the stated condition is clear enough for agent selection.

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, and non-destructive behavior, and the description adds domain-specific transparency by stating it does not create an order, confirm eligibility, or charge anything. This is useful context beyond the raw annotation flags.

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 concise sentences with the usage condition front-loaded and the behavioral exclusions clearly listed. No wasted words or redundant schema repetition.

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?

The tool is simple with only two parameters, full schema coverage, an output schema, and annotations covering safety behavior. The description fully covers the key prerequisite and side-effect expectations, leaving no critical gap for an agent to call it correctly.

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 language and package_id are already well documented. The description reinforces that package_id must come from a previously selected package, but adds little new parameter-level meaning 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 states a specific verb and resource: it prepares and returns a normal login/request link for a selected package, and explicitly distinguishes itself from order creation, eligibility confirmation, and charging. This clearly separates it from the catalog and site-check sibling 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 gives a strong precondition: use only after the user explicitly selects a package returned by the service tool. It also clarifies what the tool does not do, though it does not name alternative tools for those other operations.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds useful behavioral context by defining the exact scope of measurements and explicitly listing excluded metrics, giving the agent realistic expectations about what the tool can report. 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?

Two sentences with no wasted words. The most important usage constraint is front-loaded, followed by a compact list of measured signals and a compact list of exclusions. Every sentence 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?

The description is complete enough for selecting and invoking the tool: it states the trigger condition, the measured signals, and the explicit limitations. The output schema is present, so return values need not be described in the text. Minor gap: 'bounded page' is not fully elaborated, and there is no mention of rate limits or failure modes, but annotations and schema cover the key safety and invocation aspects.

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 (url and language) are already documented with examples and constraints. The description does not add parameter-level detail, but it does clarify what the url will be checked for (robots, structured data, sitemap, llms.txt), which subtly informs how the url parameter is used. Baseline 3 is appropriate given the schema already carries the semantic weight.

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 uses a specific verb ('inspect a public website') and explicitly names the resource and signal categories measured: bounded page, robots, structured-data, sitemap, and llms.txt. It also clearly states what the tool does not measure, which removes ambiguity and distinguishes it from any broader analytics 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 opening instruction 'Use only when a user asks to inspect a public website' gives an explicit triggering condition. The negative list ('does not measure AI mentions, rank, visibility, firewall passage, or sales') helps an agent avoid using it for those needs, though it does not name alternative tools for those cases. Siblings are catalog/order tools, so no direct site-check alternative is available to reference.

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