HireLocksmiths — Locksmith Finder

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, non-idempotent), it discloses real-world side effects the annotations cannot express: a real lead is sent to a specific person, the result is only a REQUEST, and the locksmith must confirm time, price and ETA. It even documents the return shape (reference id HL-####) with no output schema present.

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?

Short, front-loaded, and every sentence carries distinct information: the purpose, the gating condition, the required contact data, the time format, the request-vs-appointment caveat, and the return id. 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 non-idempotent, open-world mutation with no output schema, it covers the critical unknowns: it writes a real lead, it is not a confirmed appointment, and it returns a reference id. The remaining gap is that it never tells the agent where locksmith_id comes from (presumably search_locksmiths) or what the other optional fields mean.

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 0% across 9 parameters, so the description carries the full burden. It adds genuine meaning for three of them ('phone (preferred) or email' contact rule, and a format example for preferred_time), but never mentions the two REQUIRED parameters (name, locksmith_id) nor zip, details, service, or urgency, so a large part of the schema stays opaque.

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 ('Create a booking request with a specific locksmith') and immediately distinguishes itself from the sibling request_quote by characterizing itself as 'firmer'. An agent can route between the two without opening the 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?

Gives an explicit trigger ('ONLY call when the user wants to book a job'), states the consequence of misusing it ('it sends a real request'), and positions it relative to the sibling request_quote. Nothing about when to pick this tool is left 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds valuable behavior beyond that: it discloses the shape of the result (served or not, count of vetted providers, count with 24/7 emergency) and clarifies that results are not a live availability status — an important semantic limit the annotations do not capture.

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 paragraphs, the scope stated first and the important caveat second. No filler sentences; every line carries either routing or result-shape information.

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?

No output schema exists, and the description compensates by summarizing what is returned. Combined with the request_quote pointer and the availability caveat, an agent has almost everything needed, with only the both/neither-parameter behavior left unaddressed.

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%, so the description carries the burden. It adds real meaning by specifying the expected value of location ('ZIP or city') and that locksmith_id targets a single provider. It does not state whether the parameters are mutually exclusive, whether both may be supplied, or what happens when both are empty (they default to empty strings), leaving a gap in a two-mode API.

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 ('Check coverage') and enumerates the two lookup modes: one provider via locksmith_id or an area via location. It does not explicitly differentiate itself from close siblings such as search_locksmiths or get_locksmith, so an agent must infer that this is a coverage-summary call rather than a directory search.

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 routes the agent: use this for provider/area coverage checks, and use request_quote for live availability. The 'don't imply a real-time available-now status' instruction is a clear negative boundary that prevents a common misinterpretation.

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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely new behavioral facts: eta_minutes is always null, the response carries a count of vetted providers and a 24/7 coverage flag, and it explicitly warns 'Never invent a number of minutes.' That is high-value disclosure beyond structured fields.

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?

Four short statements, front-loaded with the purpose, then the null-ETA caveat, then the return shape, then the alternative and the anti-hallucination rule. No sentence is 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?

There is no output schema, so the description must carry return-value meaning, and it does: what eta_minutes is, what the tool actually returns, and where to get a real ETA. For a one-parameter read-only lookup, nothing an agent needs to call it correctly 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?

Schema coverage is 0% and the single 'location' parameter has no schema description, so the description must compensate. It does so by defining accepted formats ('ZIP or city'), which is the key semantic for the only parameter, though it adds nothing about validation or failure modes for an unrecognized location.

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?

Names a specific verb and resource ('Get an ETA proxy for a location') and clarifies the input format (ZIP or city), which is more than the name alone conveys. It also differentiates itself from the sibling request_quote by explaining that real ETAs come from there, though 'ETA proxy' remains an odd framing that the rest of the text has to walk back.

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 routes the agent: use this for the proxy signal, but 'For a real ETA, call request_quote and the locksmith confirms it directly.' That names the alternative and the condition that selects it, which is exactly the when/when-not guidance an agent needs.

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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the remaining burden is light. The description adds real value by enumerating the returned fields, which matters because no output schema exists.

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 purpose sentence is front-loaded and the return-field list follows. The list is slightly long but earns its place given the absence of an output schema.

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?

No output schema exists, so the description's field enumeration substitutes for it, and annotations handle the safety semantics. Nothing an agent needs in order to call this correctly 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?

With 0% schema description coverage on the single locksmith_id parameter, the description compensates by identifying the id as coming from search_locksmiths, which is exactly the disambiguation an agent needs. It adds no format details, but the provenance hint is meaningful.

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 ('Get the full profile for one locksmith by id') and explicitly ties it to the sibling it depends on, search_locksmiths. An agent can distinguish this from search_locksmiths or request_quote 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?

The parenthetical '(from search_locksmiths)' tells the agent where the id comes from, implying the correct call order. There is no explicit when-not guidance, but the retrieval-after-search workflow is clear from context.

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, non-destructive, and open-world. The description adds real value beyond them: prices are read live, there is no agent-side checkout so the checkout_url must be handed to the business, and a city slug unlocks extra fields. Return-field detail is present but the format of the catalog rows is only summarized.

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?

Front-loads purpose and the audience caveat, then the use-when list, then returns, then the arg. It is a bit long and the trigger list is dense, but each sentence carries distinct information with 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?

No output schema exists, yet the description enumerates the returned fields (name, price, billing, description, requires, checkout_url, signup_url) and the conditional city fields. Combined with annotations covering the safety profile and the param explanation, nothing needed to call it correctly 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?

Schema description coverage is 0% and the sole parameter has no schema description, so the description carries the full burden. It specifies that city is optional, its format (lower-case, hyphenated slug), an example ('san-antonio'), and the behavioral effect of supplying it (listing count plus exclusive-slot status).

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 resource (the HireLocksmiths product catalog) and its scope ('what HireLocksmiths sells and how to buy it'), and explicitly names the sibling it is not: search_locksmiths for consumers. An agent can tell it apart from search_locksmiths without opening a 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?

Gives an explicit trigger list (getting listed, verified badge, missed-call textback, AI receptionist, review automation, microsite, Own Your City) and an explicit exclusion ('NOT for consumers looking for a locksmith - use search_locksmiths'). The when/when-not and the alternative are all present.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it sends an actual outbound request to a third party, it returns an HL-#### reference id, and price/availability/ETA are confirmed directly by the locksmith rather than by the tool. It does not warn that non-idempotent calls can create duplicate leads, which is the one notable omission.

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?

Front-loads the critical constraint (the ONLY/when-to-use warning) before the mechanics, which is the right ordering. The arg list is long but justified by 0% schema coverage; some entries ('name: Customer name') are near-tautological but harmless.

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 still explains the return value (reference id) and what happens after the request. Annotations cover the safety profile, all 8 params are explained, and the real-world side effect is disclosed — nothing essential is missing for correct invocation.

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 0% and there are 8 parameters, so the description carries the full burden — and it does: it documents every arg, marks phone as preferred and states 'Phone OR email is required' (a constraint the schema does not express, since neither is in required), notes zip improves routing, and gives service examples matching the default.

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 ('Create a lead: ask a specific locksmith for a quote') and frames the outcome as a lead rather than a booking, which meaningfully separates it from book_job. An agent can tell immediately this is a contact/introduction request, not a reservation.

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?

Gives an explicit, exclusive precondition: 'ONLY call this when the user has chosen a provider and wants to be contacted,' plus the reason (it sends a real request). It does not name an alternative sibling (e.g. book_job) for the case where the user has not yet chosen a provider, so routing is clear but not fully disambiguated.

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, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: results are human-vetted, ranked with featured listings first, and neither price nor ETA is pre-listed, with an explicit instruction not to invent them.

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?

Front-loaded purpose sentence, then return-shape, then a compact Args block that maps one-to-one onto the five parameters with no filler. The trailing pricing caveat is short and load-bearing, and the prose is appropriately sized for a 5-param tool.

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?

No output schema exists, but the description enumerates the returned fields (id, name, city, services, rating, verified/featured flags, phone, profile URL), covers every parameter, and flags the pricing/ETA limitation. Nothing an agent needs to call this correctly 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?

Schema description coverage is 0%, so the description carries the entire burden and does: location format (5-digit ZIP preferred or city name), service with seven example values, urgency examples, budget as free-text, and limit bounds (1-20, default 5). This compensates completely for the empty schema 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?

Opens with a specific verb+resource+qualifier ("Find vetted, licensed locksmiths near a location") and immediately differentiates itself from siblings by positioning itself as the first step and deferring pricing/ETA to request_quote. An agent can tell this apart from get_locksmith, request_quote, and book_job 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?

"Use this first when a user needs a locksmith" gives an explicit entry-point condition, and the closing note routes the pricing step to request_quote. It stops short of naming exclusions (e.g., when to prefer get_locksmith for a known provider id), so it is clear context rather than a full decision tree.

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