Profissionais de serviços locais no Brasil: encanador, eletricista, diarista e +270 tipos
Scored across 10 tools
Most tools target distinct resources/actions (find vs get vs compare providers, coverage check, category listing, rating). The main overlap is estimate_job vs estimate_price, which both produce pricing estimates and could be confused, though the descriptions differentiate specific-job vs regional-range estimation.
All ten tools follow a clean, predictable verb_noun snake_case pattern (check_coverage, compare_providers, estimate_job, estimate_price, find_providers, get_provider, get_request, list_categories, rate_service, search_services). No mixed conventions.
Ten tools is well-scoped for a service-marketplace: discovery, comparison, profiling, pricing, requests, and ratings each earn a distinct tool. Nothing feels redundant or bloated.
The surface covers discovery, evaluation, pricing, and rating, but there is a notable gap: get_request reads a request's status while no tool creates a request (LQ-XXXX), and rate_service depends on an existing request. This missing create step is a lifecycle hole.
Diz se a Loqal reconhece um lugar (bairro, cidade, UF em todo o Brasil) e quantos profissionais reais atendem ali, no geral ou para uma necessidade. Use antes de prometer algo ao usuário.
| Name | Required | Description | Default |
|---|---|---|---|
| need | No | ||
| where | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, covering the safety and mutation profile. The description adds semantic context (counts 'real professionals', recognizes places at neighborhood/city/state level) but doesn't disclose return format, rate limits, or other behavioral traits beyond what annotations provide.
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, front-loaded with the core purpose followed by a usage directive. No wasted words; 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 2-param read-only tool with no output schema, the description covers purpose, usage, and parameter meaning adequately. It implies a count is returned but doesn't specify the response structure, and doesn't explicitly state that 'need' is optional (though implied by 'no geral ou para uma necessidade').
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 must compensate. It explains that 'where' is a place (bairro, cidade, UF) and that 'need' is an optional filter ('no geral ou para uma necessidade'), adding meaningful semantics beyond the bare string types. It does not detail exact format or minLength, but provides useful guidance.
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 (reconhece/atendem) and resource (lugar, profissionais) with scope (bairro, cidade, UF em todo o Brasil). An agent can tell it apart from siblings like find_providers or estimate_price, but the description does not explicitly name alternatives to reinforce differentiation.
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?
Provides a clear usage context: 'Use antes de prometer algo ao usuário' (use before promising something to the user). However, it does not specify when-not to use it or name alternative tools for related tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compara lado a lado 2 a 6 profissionais (slugs) para uma necessidade: nota, avaliações, distância, preço informado, 24h, verificação. Não inventa: "não informado" quando a Loqal não sabe.
| Name | Required | Description | Default |
|---|---|---|---|
| need | No | ||
| slugs | Yes | ||
| where | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds genuine behavioral context beyond them: the tool does not fabricate data and returns 'não informado' when Loqal lacks a value, which tells the agent how to interpret missing 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?
Two tight sentences with no filler: the core comparison action and scope come first, followed by the data-honesty caveat. 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?
With no output schema, the description usefully enumerates the returned comparison fields (nota, avaliações, distância, preço, 24h, verificação) and the null-handling rule, which is exactly what an agent needs to interpret results. The only gap is the unexplained 'where' parameter.
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 must carry parameter meaning. It does clarify the slugs constraint (2 to 6) and ties 'need' to the comparison purpose, but the 'where' parameter is never mentioned in the description or schema, leaving one of three parameters undocumented.
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 ('Compara lado a lado 2 a 6 profissionais') plus the comparison dimensions (nota, avaliações, distância, preço, 24h, verificação). This clearly separates it from find_providers and get_provider, which return a single or listed provider rather than a side-by-side comparison.
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 phrase 'para uma necessidade' implies the comparison is scoped to a need, and the 2-6 slug bound tells the agent when the tool is applicable. However, it never states when to prefer get_provider or find_providers instead, nor any exclusion conditions, so usage remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estima quanto vai custar um serviço específico descrito pelo usuário (ex.: "instalar ar split de 12 mil BTUs no 7º andar, sem infraestrutura, na Tijuca"), separando mão de obra, material e deslocamento, com as premissas e o que falta para refinar. Usa o Índice de Preços Loqal e preços reais publicados por profissionais quando existem (base=indice_loqal|precos_reais); sem eles, é uma referência de mercado (base=ia). É estimativa, não orçamento. Antes de chamar, se faltar o detalhe que mais muda o preço (tamanho, quantidade, m², BTUs), pergunte ao usuário.
| Name | Required | Description | Default |
|---|---|---|---|
| need | Yes | O caso com os detalhes do usuário | |
| niche | No | slug do tipo de profissional (search_services/list_categories); se omitido, a Loqal entende pelo texto | |
| where | No | Bairro e cidade, ou cidade e UF | |
| details | No | Respostas do usuário que mudam o preço, ex.: "12.000 BTUs", "7º andar" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnlyHint=true, destructiveHint=false); the description adds genuinely useful behavior: the data provenance and fallback (base=indice_loqal|precos_reais with real published prices, falling back to a market reference at base=ia) and the explicit limitation that the result is an estimate rather than a commitment. That is real context beyond the 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?
Purpose is front-loaded and the sentences are dense but purposeful – provenance, limitation, and the pre-call instruction each earn their place. It is bordering on long, but nothing is redundant.
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 carries the burden of describing the return: a split of labor/material/travel plus assumptions and open questions, and the base field explaining confidence. That is adequate, though it never clarifies how this differs from the sibling estimate_price, which is the main completeness 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 coverage is 100%, so 3 is the baseline. The description goes slightly beyond it by supplying a worked example of what 'need' should contain ('instalar ar split de 12 mil BTUs no 7º andar, sem infraestrutura, na Tijuca') and framing 'details' as the answers that move the price, which helps the agent populate the free-text fields.
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 ('Estima quanto vai custar um serviço específico descrito pelo usuário') and even enumerates the output breakdown (mão de obra, material, deslocamento), which makes the tool's role concrete. However, it never distinguishes itself from the sibling 'estimate_price', leaving the agent to guess which estimator to pick.
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 pre-call rule – if the price-dominant detail (size, quantity, m², BTUs) is missing, ask the user first – and clarifies this is an estimate, not a budget. But there is no when-to-use vs alternatives guidance, and the obvious overlapping sibling 'estimate_price' is never addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Faixa de preço de um serviço numa região, só com preços reais: dos profissionais perto (5 ou mais) ou do Índice de Preços Loqal (preços publicados pelos próprios negócios, por estado ou nacional; source=indice_loqal, com página de referência). Sem dados suficientes, diz que não há e não inventa valores.
| Name | Required | Description | Default |
|---|---|---|---|
| need | Yes | ||
| where | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (read-only, non-destructive, idempotent), but the description adds real behavioral value: prices are only real, a minimum of 5 nearby professionals is required, the Loqal index fallback is state or national with a reference page, and it refuses to fabricate when data is insufficient. This is meaningful disclosure beyond 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?
Front-loaded with the core outcome (price range for a service in a region) and then the sourcing/fallback detail. Dense but every clause carries information; no padding, though the parenthetical is slightly run-on.
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, yet the description explains what is returned (a price range plus its source/reference) and the failure mode (states there is not enough data rather than inventing values). Combined with the annotations, an agent has enough to call it correctly; only the parameter meanings remain underspecified.
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% for both parameters, so the description carries the burden. 'de um serviço numa região' weakly maps to need and where, but neither parameter is named or explained, and the mention of source=indice_loqal introduces a value not present in the schema, which could mislead.
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: returns a price range for a service in a region, and specifies the two data sources used. It is clear about scope, though it does not differentiate itself from siblings like estimate_job or compare_providers, which an agent could plausibly confuse with it.
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 ('faixa de preço de um serviço numa região') and the description explains the internal condition for choosing a source (5+ nearby professionals vs. the Loqal index), but it never states when to pick this tool over estimate_job or compare_providers. No explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Encontra profissionais reais perto de um lugar para uma necessidade. Ex.: need="instalar 3 ventiladores", where="Tijuca, Rio de Janeiro", min_rating=4.5, max_price_brl=350. Retorna perfis estruturados (nota, avaliações, distância, preço quando informado) e uma tela com cards.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude (busca geolocalizada: use com lng quando o usuário compartilhar a localização) | |
| lng | No | ||
| need | Yes | O que o usuário precisa, com as palavras dele | |
| sort | No | ||
| limit | No | ||
| niche | No | Slug exato do tipo de profissional (de list_categories), ex.: "motorista", "pedreiro". Quando informado, vence a interpretação do texto. | |
| where | No | Bairro e/ou cidade, ex.: "Tijuca, Rio de Janeiro" ou "Pinheiros SP" | |
| service | No | Subcategoria exata, a service_key de search_services (ex.: "piscina/limpeza"). Prioriza quem faz exatamente isso, sem esconder o resto do tipo. | |
| radius_km | No | Raio da busca em km a partir de lat/lng ou do lugar (padrão: 5 a 15 km conforme o lugar) | |
| min_rating | No | ||
| min_reviews | No | ||
| emergency_24h | No | Só quem atende 24 horas / emergência | |
| max_price_brl | No | Mantém quem não informou preço (cobra por orçamento) |
| Name | Required | Description |
|---|---|---|
| total | Yes | |
| providers | Yes | |
| loqal_page | Yes | |
| understood | Yes | |
| related_niches | No | Presente quando o tipo pedido ainda não tem ninguém na região e a lista é de tipos afins |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description adds genuinely new context: it returns structured profiles (rating, reviews, distance, price) plus a UI 'tela com cards', and it discloses that max_price_brl keeps providers who quoted by orçamento rather than price. Missing only pagination/limit behavior.
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?
Three front-loaded sentences: purpose, worked example, return shape. Every part earns its place, though the example is somewhat long and consumes space that could have covered uncovered parameters.
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 13-parameter search with an output schema and rich annotations, the description covers intent, a realistic example, key parameter precedence rules, and return contents. Gaps are minor (sorting/limit semantics), and the output schema removes the need to explain return values in depth.
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 62%, and the description supplies a full example that demonstrates how need/where/min_rating/max_price_brl combine, plus a clarifying hint for max_price_brl. It does not compensate for the undocumented params (sort, limit, min_reviews), so it sits at the baseline for partial coverage.
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 ('Encontra profissionais reais perto de um lugar para uma necessidade') and grounds it with a concrete example call. It implicitly separates itself from get_provider/compare_providers by being a discovery search, but never names those siblings explicitly, so differentiation is left partly to inference.
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 worked example shows how to invoke it, and it notes that niche 'vence a interpretação do texto' and that service prioritizes exact matches — useful behavioral guidance. However there is no explicit when-to-use-this-vs-alternatives statement relative to siblings like search_services or compare_providers, so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perfil completo de um profissional (slug vindo de find_providers): serviços com aliases e preço inicial, bairros atendidos, nota com a fonte, avaliações recentes, ações e o índice de preparo para IAs (agent_readiness).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, setting a lower bar. The description adds value by disclosing the actual return payload (services with aliases and starting price, neighborhoods, rating with source, recent reviews, agent_readiness index), which goes beyond the 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?
A single dense sentence, front-loaded with the core identity ('Perfil completo de um profissional') followed by the input source and content list. No wasted sentences, though the content enumeration is heavy.
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 bears the burden of describing returns — and it enumerates the key fields well. Combined with annotations covering the safety profile, this is nearly complete; only edge behavior (e.g., what happens on an unknown slug) is unstated.
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% for the single 'slug' parameter, so the description must carry meaning. It does identify the value's origin (comes from find_providers), which is genuinely useful, but adds no format or constraint details (e.g., URL-format slug, case sensitivity).
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+resource: the complete profile of a professional. It names the sibling that produces the required input (find_providers) and enumerates the profile contents, so an agent can distinguish it from list/search 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?
Usage is implied through the parenthetical '(slug vindo de find_providers)', which establishes the intended flow of find_providers → get_provider. There is no explicit statement of when not to use it or how it compares to compare_providers or estimate_price.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Situação de um pedido pelo código (LQ-XXXX): status e profissionais que receberam. Respostas de orçamento chegam no WhatsApp do usuário.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context: it returns request status and professionals, and notes that budget responses arrive via WhatsApp rather than through this tool.
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 tightly written sentences. The purpose is front-loaded, and the WhatsApp note adds a useful expectation without wasting words.
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 one-parameter lookup with no output schema, the description covers purpose, input format, and return content well. It could say more about errors or response structure, but safety and scope are already covered by annotations.
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 must carry parameter meaning. It does by naming the required code and giving the LQ-XXXX format, which helps the agent supply a valid value.
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 retrieval action and resource: request status by code, with returned fields (status and professionals). It is clear what the tool does, though it does not explicitly distinguish itself from 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 implies usage requires a code but gives no explicit when-to-use guidance, prerequisites, or alternatives. It does not route the agent away from other tools or clarify when this lookup is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Setores e nichos da Loqal (285 tipos de serviço), com quantos profissionais reais atendem. Filtre por setor (slug) ou por lugar para ver só o que existe ali.
| Name | Required | Description | Default |
|---|---|---|---|
| where | No | ||
| sector | No | slug do setor, ex.: reformas-e-reparos |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds useful context that results are scoped to categories that actually have real professionals, but it says nothing about ordering, pagination, or result size for the 285 entries.
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 tight sentences, front-loaded with what the tool returns and followed by the filtering options. The parenthetical "(285 tipos de serviço)" earns its place as scale context; nothing is redundant.
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 and only two optional parameters, the description does enough: it conveys that the response is a catalog of sectors/niches accompanied by professional counts. It could be more explicit about the returned shape, but the essentials for a correct call are 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 only 50% because the `where` parameter has no description; the description compensates by explaining that "where" filters by place ("lugar") and confirms `sector` is a slug. This adds genuine meaning beyond the raw schema, though it gives no format examples for the place value.
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 the resource concretely: sectors and niches (285 service types) with counts of real professionals, which tells an agent this is a taxonomy/catalog listing rather than a provider or service search. It does not explicitly contrast itself with siblings like search_services or find_providers, so it stops short of a 5.
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?
"Filtre por setor (slug) ou por lugar para ver só o que existe ali" gives the filtering intent but no when-to-use guidance relative to sibling tools such as search_services or check_coverage. Usage is implied rather than stated, and there are no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registra a avaliação do usuário para um profissional que recebeu o pedido dele (código LQ-XXXX). Só aceita avaliação ligada a um pedido real: é o que torna a reputação da Loqal confiável.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| rating | Yes | ||
| comment | No | ||
| provider | Yes | slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=false and destructiveHint=false, so the agent knows this is a non-destructive but mutating, non-idempotent write. The description usefully adds the business rule that only ratings tied to a real order are accepted, but says nothing about duplicates (error vs. append), immutability, or auth requirements — gaps that matter for a non-idempotent mutation.
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 tight sentences, no filler. The operational purpose is front-loaded and the second sentence earns its place by stating the hard constraint and why it exists for the platform's reputation.
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 4-parameter mutation with no output schema and no parameter descriptions, the description covers the essential precondition but leaves meaningful gaps: duplicate-rating behavior, whether the comment is optional, error handling for an invalid code, and permission requirements. There is no output schema to explain return values, so that omission is acceptable.
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 25% — just 'slug' for provider — so the description must compensate and partially does, revealing the code format (LQ-XXXX) and that the provider is the professional who received the order. It adds nothing about the optional comment field or the rating scale beyond what the integer 1–5 bounds already encode in 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 names a specific verb and resource: it registers a user's rating for the professional who served their request, and scopes it to an existing order code (LQ-XXXX). That is unambiguous and clearly distinct from retrieval/listing siblings like get_provider or get_request, though no sibling is named 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 states one real precondition — the rating must be linked to an actual order ('Só aceita avaliação ligada a um pedido real') — which tells the agent when a call will be rejected. However it never states when to use this tool versus alternatives (e.g., after get_request completes), so usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mapeia uma necessidade em linguagem natural ("cano da pia vazando", "limpar ar-condicionado") para os serviços da Loqal. Use quando não estiver claro qual profissional resolve.
| Name | Required | Description | Default |
|---|---|---|---|
| need | Yes | A necessidade, com as palavras do usuário |
| Name | Required | Description |
|---|---|---|
| matches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description only implies a semantic mapping operation and says nothing about matching quality, fallback behavior when no service matches, or result ranking.
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 tight sentences: the function first, the usage trigger second, with zero filler. Front-loaded and immediately actionable.
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 an output schema present, return values need not be described, and the annotations carry the safety semantics. What remains missing is minor: no hint about match ambiguity or what to do when nothing maps, which matters for a fuzzy natural-language matcher.
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?
Only one parameter and schema coverage is 100%, so the schema already documents 'need'. The natural-language examples in the description reinforce the free-text expectation but add little beyond what the schema field description already states.
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?
Concrete verb+resource: maps a natural-language need onto Loqal services, with concrete input examples. It is clearly distinct from sibling lookups like list_categories or find_providers, though it never names those siblings to sharpen the boundary.
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 quando não estiver claro qual profissional resolve" gives explicit when-to-use and implies when-not (once the category/provider is known, the lookup tools apply). It stops short of naming the alternative tools, but the trigger condition is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
estimate_jobcheck_coveragecompare_providersestimate_pricefind_providersget_providerget_requestlist_categoriesrate_servicesearch_servicesUS local-services data: find locals by trade and city, browse open jobs, see which markets answer
Empresas do Google Maps no Brasil com telefone, e-mail, site e CNPJ da Receita Federal.
Extract local businesses from Google Maps in Brazil with phone, email, website and CNPJ.
Find local service providers — plumbers, tutors, translators — and estimate provider earnings.
Add one secure layer between your agents and this server.
