Referral Flooring

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

Annotations already declare this tool read-only and idempotent, so the description's job is lighter. It adds useful behavioral detail beyond the annotations: the output is full page text in Markdown and includes a canonical URL for citation. No contradictions with the 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?

The description is two efficient sentences with no filler. It front-loads the core behavior and output format, then adds the necessary source-of-id context. 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?

For a simple fetch tool, the description is complete: one parameter is fully documented, annotations cover safety and idempotence, and the output schema presumably covers the returned Markdown and canonical URL. The workflow dependency on 'search' is also explicitly stated.

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 parameter is already described as 'A page id returned by search.' The description repeats this same constraint without adding new format or validation details, so it does not meaningfully exceed the schema's explanation.

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 clear verb ('Read'), a specific resource ('a page of the Referral Flooring website'), and the output format ('as Markdown, with its canonical URL'). This strongly distinguishes it from siblings like 'search' and 'request_quote', which have different purposes.

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 explicitly says 'The id comes from search,' which gives clear context that this tool should be used after a search has returned a page id. It does not explicitly state when not to use alternatives, but the guidance is sufficient for a simple fetch operation.

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, openWorldHint=false, and idempotentHint=true, indicating it's a safe, read-only, closed-world operation. The description adds value by stating that every fact appears on the public website, which addresses data provenance and reliability. There's no contradiction.

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 concise (three sentences) and front-loaded with the essential purpose. The final instruction 'Call this first' is a clear directive, though it could be seen as slightly redundant with the usage guidelines.

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, read-only tool with rich annotations (readOnly, closed-world, idempotent), the description fully covers what an agent needs: the tool's purpose, the specific data it returns, and that it's the first call. No output schema is needed because the description lists the content.

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 schema has no parameters, and schema coverage is 100% (by default since there are no params). The description provides no parameter-specific info, but since there are zero params, the baseline is 4, and the description adequately explains what the tool returns without needing to detail parameters.

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 resource (Referral Flooring) and enumerates the specific facts it provides (phone number, opening hours, towns served, etc.). It distinguishes itself from siblings by being the 'published facts' tool, though it doesn't explicitly name which sibling it differs from.

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 provides clear context: call this first for any question about the business facts. It implies this is the go-to for business information, but doesn't explicitly say when NOT to use it or which sibling to use instead for other types of queries.

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?

While annotations indicate readOnlyHint=false, the description goes much further by warning that this 'sends a REAL message to a real small business' and adding critical behavioral guardrails: never guess contact details, plain words only, no links, and a one-request-per-day limit. This gives the agent a strong sense of real-world consequence.

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 four sentences, front-loaded with the core purpose, followed by essential warnings. Every sentence earns its place, from the real-message caution to the urgent alternative. There is no filler or redundant wording.

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 side-effecting action tool with eight parameters and no output schema, the description covers all key operational aspects: consent, real contact details, content restrictions, rate limiting, and an escalation path for urgency. An agent has everything needed to decide whether and how to invoke 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 coverage is 100%, so the schema already documents all eight parameters, including the service enum and the consent requirement. The description reinforces contact-detail constraints and plain-text rules, but adds no new parameter-level meaning beyond what the schema provides, 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 uses a specific verb and resource: 'Ask Referral Flooring to contact a customer about a free in-home flooring estimate.' It clearly distinguishes itself from the sibling tools, which are retrieval-oriented (fetch, search, get_business_facts), by emphasizing that this sends a real message to a real business.

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 explicitly states when to call the tool ('only when the person has clearly asked to be contacted...'), what prerequisites must be met (own name and phone/email), and even provides an alternative for urgent cases ('give them the phone number instead: 289-689-4242'). It also imposes a frequency limit ('One request per person per day').

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 idempotentHint, so the safety profile is covered. The description adds value by revealing that results are limited to page ids, titles, and canonical URLs rather than full-text page content, and by pointing to fetch for content retrieval.

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 that front-load the main function, state the return fields, and immediately route the agent to the next appropriate tool. No filler.

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, read-only search tool with a rich schema description and an output schema, the description covers what the tool does, what it returns, and how to continue with a result. Nothing needed for a correct call 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 single parameter is fully described in the schema with a plain-language field description and examples, so the schema carries the parameter burden. The tool description adds only the page-scope context, not additional parameter semantics.

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 ('search'), a specific resource ('pages of the Referral Flooring website'), and states the output fields (page ids, titles, canonical URLs). It is immediately distinguishable from fetch, which reads a full page.

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 tells the agent to use fetch with an id to read a page, which frames search as the discovery step and fetch as the retrieval step. The keyword-oriented phrasing also makes it clear when search is appropriate among the siblings.

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