HeySale — AI Website Salesperson

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

Annotations already declare readOnlyHint, openWorldHint=false, and idempotentHint=true, so the safety profile is covered. The description adds useful context about what the read-only check actually reveals: reading completion, visitor readiness, and script detection on the live site. 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?

A single, well-structured sentence that states the two key checks without unnecessary wording. It is front-loaded and every part adds meaning.

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, single-parameter status check, the description is sufficient for correct invocation. It explains what is being checked, and the absence of an output schema is not a serious gap because the description frames the result as answering a yes/no-style status question.

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 only parameter, salesperson_id, is already documented as 'The id returned when the salesperson was created.' The tool description adds no further parameter details, but none are needed at this baseline.

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 names a specific verb ('find out whether') and a specific resource (website salesperson status), and pinpoints the exact checks: readiness to talk to visitors and script detection on the live site. This clearly distinguishes it from siblings like create_website_salesperson or configure_salesperson.

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 makes the tool's purpose clear enough that an agent can infer when to call it, but it does not explicitly say when to use it instead of siblings such as get_salesperson_installation or get_salesperson_results. There is no exclusions or alternative 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?

The description discloses that changes apply 'in every conversation' and requires the website owner's API key, which are behavioral details not covered by the annotations. It does not mention potential side effects like rate limits or whether existing conversations are affected, but the core modifying nature is transparent.

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 concise sentences, front-loading the primary purpose and then the authentication requirement. No redundant wording or unnecessary details.

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 a configuration tool: it states what can be changed, the scope of the change, and the required credential. With no output schema, there is no need to describe return values. Minor gaps include error behavior or effects on existing conversations, but these are not critical for the core use case.

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 description maps 'name, opening line, or goal' to the name, greeting, and objective parameters, providing semantic context. It also clarifies the api_key parameter as the website owner's key. However, salesperson_id is not explicitly explained, and the schema descriptions for objective and api_key already partly cover this.

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 clearly states the tool's purpose with a specific verb ('change') and resource ('salesperson'), listing the exact attributes (name, opening line, goal). It distinguishes itself from siblings like create_website_salesperson by focusing on modification rather than creation.

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 usage for updating an existing salesperson's configuration, but it does not explicitly contrast with the creation tool or state when to prefer this over alternatives. The API key requirement is mentioned as a prerequisite, but no direct when-to-use guidance is given.

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?

The description explains that the salesperson reads the site itself and returns a one-line script to install. It also notes 'Safe to call twice,' aligning with the idempotentHint annotation and providing transparency about repeated calls.

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 long, with no redundant phrases. It front-loads the core action and follows with the use case and key input, making it efficient and easy to parse.

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?

Since there is no output schema, the description adequately explains the return value ('a one-line script to install') and the behavior of reading the website. Combined with the sibling tools for status and results, it provides enough context for correct usage.

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 80% with descriptions for website_url, business_name, integration_source, and external_project_id; only campaign lacks a description. The tool description does not add significant meaning beyond the schema—it only reaffirms that website_address is provided, which is already clear from 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 clearly states the action: 'Give any public website an AI salesperson' and its purpose of answering questions and capturing leads. It distinguishes this tool from siblings like check_salesperson_status or get_salesperson_results by focusing on creation and installation.

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 states 'Use this when someone wants to add a salesperson, live chat, a sales assistant or a chatbot alternative to a site' and even covers the goal of converting visitors. This leaves no ambiguity about when the tool is 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 idempotentHint=true, covering the safety profile. The description adds value by specifying what the tool returns (script, placement, detection status), which is behavioral context beyond the annotations. No contradictions.

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 a single, front-loaded sentence that states the primary output and two additional details. No filler words; every element 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 tool with one parameter, the description is partially complete: it explains the return content but omits the parameter semantics and any error/edge-case behavior. Given no output schema, the description could be richer about the response structure, but it is adequate for basic usage.

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 0% and the description does not mention the salesperson_id parameter at all. An agent is left to infer from the parameter name and schema pattern, but no guidance is given on its purpose or format. This is a critical 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 clearly states the tool returns the exact one-line install script, where to place it, and detection status. It uses a specific verb ('Return') and resource ('install script'), and the sibling tools (check status, configure, create, get results) are distinct in function, so no confusion.

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 — an agent would infer this tool is for retrieving installation instructions, but there is no explicit guidance on when to prefer it over siblings like configure_salesperson or check_salesperson_status. No exclusions or alternatives are mentioned.

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 mark the tool as readOnly and idempotent. The description adds an important operational constraint: it requires the website owner's HeySale API key, indicating an auth-sensitive read operation. 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 concise sentences with no filler: the first states what the tool does, the second states the prerequisite. The most important information is front-loaded.

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 conveys the general result and the auth requirement, but with no output schema it does not describe the return shape. It also omits the days parameter and how the time window affects the summary, leaving a moderate gap for a 3-parameter 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 description coverage is only 33%, and the description does not clarify salesperson_id or the optional days parameter. It mostly restates the API key requirement already present in the schema and focuses on output rather than parameter meaning.

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, 'Summarise', and lists concrete metrics: visitors talked to the salesperson, details left, and top questions. This clearly communicates the tool's purpose and naturally differentiates it from installation, status, and configuration 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?

No guidance is given on when to use this tool versus alternatives such as check_salesperson_status or get_salesperson_installation. The API key requirement is a prerequisite, not a selection criterion.

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