availability

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context: it reports a point-in-time state ('free right now') plus a data-freshness signal ('when they last set their availability'), which is meaningful given there is no output schema.

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 tight sentence that front-loads the core action ('Check whether one specific named business is free right now') before the secondary return detail and the usage rule. No filler or redundancy.

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-parameter read tool with full schema coverage and annotations handling the safety profile, the description is nearly complete and even hints at return content. It omits only edge behavior such as what happens when the name matches nothing or is ambiguous across branches.

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 both parameters are already well documented in the schema, including the 50-mile widening behavior for postcode. The description adds nothing about parameter format or matching semantics (e.g., partial-name matching), so the baseline 3 for schema-covered params 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 description gives a specific verb and resource (check availability for a single named business) and pins the scope with 'one specific named business.' That singular framing implicitly contrasts with the plural sibling find_available_providers, but the sibling is never named, so differentiation is inferred rather than stated.

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?

'Use this when someone names a business rather than a trade' is an explicit routing rule that separates this tool from the trade-search path. It gives a clear positive condition but does not name the alternative tool or state any exclusion (e.g., what to do when only a trade is known).

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?

Beyond the readOnly/openWorld annotations, the description explains the core mechanic (providers set their own traffic light, green/amber/red, expiring on a timer) so the agent understands what a result actually means. It discloses geographic coverage (UK, densest in Lancashire, plus Ibiza, Pattaya, Dubai, Las Vegas), that the tool answers plainly when nobody is found, and that the credential filter may legitimately return nobody. It also flags cost/latency ("cheap, it answers in one 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?

It is front-loaded: the what, then the when-to-call rule, then coverage, then the cost rationale. Most sentences carry distinct information. There is some bloat from all-caps emphasis and from restating the value of asking twice ("there is no cost to checking and a real cost to guessing" / "It is cheap, it answers in one call"), which makes it longer than strictly necessary.

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 7-parameter, all-optional, read-only search with no output schema, the description covers intent, scope, coverage, and result semantics well enough to call it confidently. What is missing is any indication of what a successful result contains — provider name, contact details, distance, the traffic-light state — even though the traffic-light concept is explained. Everything else an agent needs before invoking is present.

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 defines every parameter, and the description's main added value is reinforcing that the location refers to where the work is, not where the user is ("Works for ANY area you name, not only where the user is — give it the town, postcode or island the work is in"). It also warns against inferring coverage from request wording, which affects how the trade/job parameters should be filled. It does not add syntax or format detail beyond the schema, so it sits just above the 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 opening sentence gives a concrete verb and resource ("find a person to do something in a named place") plus the distinctive output dimension ("say which of them are ACTUALLY FREE RIGHT NOW"). It is clearly a search tool, not a directory lookup. The only weakness is that it never mentions the sibling check_provider_availability; instead it claims to be "the ONLY source for who is free right now," which leaves the boundary between the two availability tools unstated.

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 an explicit call condition ("CALL THIS FOR ANY REQUEST OF THE SHAPE 'I need a <person> in <place>'") and an explicit anti-pattern ("Do NOT judge from the wording whether Speedi is likely to cover it"), then reinforces both with a long list of examples spanning travel, hospitality, lifestyle and admin requests. The alternative it rules out is named — web search — with the reasoning that the web cannot answer who is free right now. Coverage areas and the fact that asking is cheap close the loop on when to call.

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?

Despite the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) already signaling a non-destructive but state-changing, outward-facing operation, the description adds real substance: an email is sent the moment the business goes green, cancellations count as triggering events, and every message carries one-click opt-out. It also surfaces a consent requirement (ask for the email in the person's own words, never invent or reuse one) that no annotation encodes.

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 definition is front-loaded: the action comes first, then when to use it, then prerequisites and behavior. The email-safety instruction is restated twice (ask in their own words, never invent/reuse), which is mild redundancy against the schema's own field note, but it is deliberate compliance emphasis rather than 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 two-parameter, no-output-schema mutation tool, everything an agent needs is present: when to invoke it, where the id comes from, how the email must be obtained, what the side effect is, and how the recipient can unsubscribe. Nothing material is left to inference, and the annotations already cover the safety profile.

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 both parameters are already documented and the baseline is 3. The description adds provenance semantics by tying providerId to find_available_providers ('exactly as returned') and stresses the consent/derivation rule for email, which goes beyond the schema's short field hints.

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 action and object: have Speedi notify someone when a particular business 'sets its light green'. It also distinguishes itself from the siblings by framing the tool as the fallback for 'nobody is available' rather than a lookup, so an agent can separate it from find_available_providers and check_provider_availability without opening any 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?

It states the exact selection condition ('when nobody is free now and the person wants one business in particular') and explicitly warns that this is not a weak alternative to availability ('the answer to "nobody is available", not a consolation'). It also names the prerequisite path: get the provider id from find_available_providers, and get an email from the person.

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