Catálogo de software do Brasil: fichas com a origem de cada dado, preços em reais e comparação.
Scored across 9 tools
Each tool targets a clearly different need: search (buscar_softwares), details (obter_ficha), comparison (comparar_softwares), similar items (alternativas), category aggregates (estatisticas_da_categoria), raw reviews/complaints (listar_avaliacoes, listar_reclamacoes) and aggregated reputation (obter_reputacao). The descriptions explicitly route from search to ficha and clarify that reputação is a computed summary vs. the raw listings. Only mild conceptual proximity exists between reputação and the review/complaint listings, and the descriptions resolve it.
Predominantly consistent verb_noun in Portuguese (buscar_softwares, comparar_softwares, listar_categorias, listar_avaliacoes, listar_reclamacoes, obter_ficha, obter_reputacao). Two deviations stand out: 'alternativas' (bare noun, no verb) and 'estatisticas_da_categoria' (noun phrase instead of verb_noun). Still highly readable and predictable overall.
Nine tools is well within the ideal 3-15 range and each maps to a distinct catalog workflow (discover, inspect, compare, aggregate, social proof). No redundant or trivial tools appear to be padding the surface.
Covers the full read-only catalog lifecycle: categories, search, ficha, comparison, alternatives, category stats, reviews, complaints, and reputation. Minor gaps exist, such as no direct lookup by fornecedor/supplier or cross-catalog free-text search over reviews, which agents would have to work around via search + ficha.
Lista outros softwares publicados nas mesmas categorias de um software do catálogo, com as categorias em comum, primeiro os que têm mais categorias em comum. Use quando a pessoa pedir alternativas, concorrentes ou substitutos de um software.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug do software, como vem da busca ou do endereço softoteca.com.br/software/{slug}. | |
| pagina | No | Página dos resultados, a partir de 1. São 20 por página. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuine behavioral value beyond that: it discloses that each result includes the categories in common and that results are sorted by descending shared-category count, which the annotations cannot convey.
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 first states what is returned and how it is ordered, the second states when to use it. Nothing is redundant and the core behavior 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?
For a read-only, non-open-world listing tool with a fully documented two-parameter schema and no output schema, the description covers purpose, trigger, and result ordering well. It could be slightly more complete by noting that pagination limits results to 20 per page in prose, but the schema already carries that.
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 documented there (slug format/source, pagina with 20-per-page semantics). The description adds no parameter-level detail such as slug format or pagination interaction, so the baseline 3 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?
Specific verb+resource: it lists other catalog software published in the same categories as a given software, and even states the ordering rule (most shared categories first). It is clearly distinct in intent from comparar_softwares and obter_ficha, though it never names a sibling explicitly, which is what separates a 4 from 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?
The second sentence gives an explicit trigger: use it when the user asks for alternatives, competitors, or substitutes for a software. That is clear context for invocation, but there are no exclusions and no routing to alternative tools for adjacent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Busca softwares no catálogo publicado da Softoteca, o catálogo de software do Brasil (B2B e B2C), com preços em reais. Use quando a pessoa pedir indicação, lista ou opções de software para uma necessidade (ex.: controle de ponto, ERP, emissão de nota fiscal), com filtros opcionais de categoria, tipo, plataforma e preço máximo. Devolve até 20 softwares por chamada, em ordem alfabética, com resumo factual, fornecedor, categorias, menor preço publicado e url_canonica. Para os detalhes de um software, use obter_ficha.
| Name | Required | Description | Default |
|---|---|---|---|
| tipo | No | B2B para software de empresas, B2C para software de consumidores. Software que atende os dois entra nos dois. | |
| origem | No | Origem da empresa fornecedora: brasileira (sede no Brasil, comprovada no site do fornecedor) ou internacional (a filial brasileira de grupo estrangeiro conta como internacional). Fica de fora o software cujo fornecedor ainda não tem a origem comprovada; nas respostas, ele vem com fornecedor.origem null. | |
| pagina | No | Página dos resultados, a partir de 1. São 20 por página. | |
| consulta | Yes | O que se procura, em poucas palavras (ex.: "controle de ponto", "emissão de NFS-e"). Cada palavra precisa aparecer no nome, no resumo, na descrição, no fornecedor ou nas categorias, sem diferença de acento ou de maiúsculas. Pode ficar vazia quando houver outro filtro. | |
| categoria | No | Slug da categoria, como vem da lista de categorias (ex.: "controle-de-ponto"). Veja listar_categorias. | |
| plataforma | No | Plataforma em que o software precisa rodar: web, windows, macos, linux, ios, android. | |
| preco_max_brl | No | Preço máximo em reais. Fica o software com plano gratuito ou com ao menos um plano de preço publicado até esse valor, na periodicidade do próprio plano (mensal, anual ou pagamento único). O plano com preço em dólar ou euro não entra neste filtro: a Softoteca não converte. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the heavy safety lifting is done. The description adds genuinely useful behavior beyond them: 20 results per call, alphabetical ordering, and the exact payload returned (resumo factual, fornecedor, categorias, menor preço, url_canonica).
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 sentences, front-loaded with purpose, then trigger conditions, then the return contract and the handoff to obter_ficha. Every clause carries information an agent needs and nothing is repeated.
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 specifying result count, ordering, and returned fields. With seven fully described parameters and annotations already covering the safety profile, 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 100%, so the enum and field semantics (tipo, origem, plataforma, preco_max_brl) are already fully documented. The description only restates that categoria, tipo, plataforma and preço máximo are optional filters, adding no new meaning beyond the schema; baseline 3 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?
States a specific verb and resource ("Busca softwares") plus the exact corpus it searches (catálogo publicado da Softoteca, B2B e B2C, preços em reais), which immediately separates it from siblings that operate on a single software or on aggregate statistics.
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 ("Use quando a pessoa pedir indicação, lista ou opções de software para uma necessidade") with concrete examples, and routes detail lookups to obter_ficha. It does not mention alternativas or comparar_softwares, so the agent must infer when a comparison or alternatives query should leave this tool — a gap, but the core routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compara de 2 a 4 softwares do catálogo lado a lado: quadro com preço, campos da ficha, integrações e conformidade, com a origem e a fonte de cada valor. Use quando a pessoa quiser saber a diferença entre softwares ou escolher entre eles.
| Name | Required | Description | Default |
|---|---|---|---|
| slugs | Yes | De 2 a 4 slugs de softwares diferentes, como vêm de buscar_softwares. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real value beyond that: the output is a comparison table and each value carries its origin/source, and only 2-4 items are accepted — useful expectations for a read tool with 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?
Two tight sentences with no filler: the capability and its scope come first, the when-to-use cue second. Nothing repeats the title or wastes space.
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 a 1-param schema and no output schema, the description adequately covers purpose, invocation intent and return shape (table plus provenance). Minor omissions remain, such as behavior with unknown or duplicate slugs, but nothing essential for correct invocation 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 100% and the single parameter already documents the 2-4 slug constraint and its origin (buscar_softwares). The description restates the 2-4 range but adds no new syntax, format or edge-case meaning, so the baseline 3 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?
States a specific verb (compara) and resource (2 a 4 softwares do catálogo) and enumerates exactly what the comparison returns: preço, campos da ficha, integrações, conformidade, com origem e fonte. This clearly separates it from single-record siblings like obter_ficha or search-oriented buscar_softwares.
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 a pessoa quiser saber a diferença entre softwares ou escolher entre eles" gives an explicit triggering intent. It stops short of naming alternatives (e.g., use obter_ficha for one software) or stating when-not, so it is clear context without explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Números da categoria calculados das fichas publicadas: quantos softwares publicam preço; o menor, a mediana e o maior preço em reais por usuário e por empresa por mês; plano gratuito e teste grátis; o menor plano de cada software; e o raio-X das fichas técnicas (API, app, LGPD, interface e suporte em português, origem da empresa e integrações mais comuns), com a definição e a base de cada número. precos vem null com menos de 3 softwares com preço publicado; raio_x, com menos de 3 fichas com ficha técnica. Use quando a pessoa perguntar quanto custa um tipo de software, quantos publicam preço ou quantos têm um recurso. Cite a url_canonica da seção (precos ou raio_x) e a data.
| Name | Required | Description | Default |
|---|---|---|---|
| categoria | Yes | Slug da categoria, como vem da lista de categorias (ex.: "controle-de-ponto"). Veja listar_categorias. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive behavior, and the description adds important context beyond them: precos is null when fewer than 3 softwares publish a price, raio_x is null when fewer than 3 profiles exist, and each number carries its definition and base. This nullability and provenance disclosure is exactly the kind of behavioral detail annotations cannot convey.
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 dense opening sentence front-loads the returned metrics, followed by null-threshold rules and usage guidance in a logical order. It is long but nearly every clause carries distinct information; the enumeration of metrics could be tightened slightly.
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 enumerates the return fields, explains when sections are null, mandates citing the source URL and date, and points to listar_categorias for the input. An agent has everything needed to call it and correctly present results.
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 categoria parameter is fully documented in the schema with an example slug and a pointer to listar_categorias. The description adds no further syntax or format guidance, so the baseline of 3 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 names a specific resource (category statistics derived from published profiles) and enumerates exactly what is computed: price counts, min/median/max price per user and per company, free plan and trial, cheapest plan, and technical-profile coverage. This is far more specific than the sibling names imply and lets an agent tell it apart from listar_categorias or buscar_softwares.
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 explicit trigger conditions: 'Use quando a pessoa perguntar quanto custa um tipo de software, quantos publicam preço ou quantos têm um recurso.' It also specifies a follow-up requirement to cite url_canonica and the date. It stops short of naming sibling alternatives to route away from, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Avaliações publicadas de um software, com as notas, os pontos positivos e negativos, o selo de uso verificado e a resposta do fornecedor, das mais recentes para as mais antigas.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug do software, como vem da busca ou do endereço softoteca.com.br/software/{slug}. | |
| pagina | No | Página dos resultados, a partir de 1. São 20 por página. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so safety behavior is covered. The description adds useful behavioral detail beyond annotations: it lists the returned fields and states the sort order (newest to oldest), which is especially valuable because no output schema is provided.
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 well-structured sentence that front-loads the core resource and then efficiently lists returned content and ordering. There is no redundant or wasted text.
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, two-parameter listing tool with rich annotations and 100% schema description coverage, the description supplies the missing return-value context (fields and sort order). No output schema exists, but the description adequately compensates.
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%, so both parameters are fully documented in the schema. The description only implies the required software identifier via 'de um software' and adds no further meaning for slug or pagina, so baseline 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 clearly identifies the resource: published reviews for a specific software, including ratings, pros/cons, verified-use badge, and vendor response, ordered newest to oldest. It distinguishes itself from listar_reclamacoes by focusing on reviews rather than complaints, though it does not explicitly name sibling alternatives.
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 states what the tool returns but gives no explicit guidance on when to use it versus siblings such as listar_reclamacoes, obter_ficha, or obter_reputacao. Usage is only implied by the content description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista as categorias do catálogo que têm software publicado, com o slug, o tipo (B2B ou B2C) e quantos softwares cada uma tem. Use para achar o slug certo antes de buscar_softwares com filtro de categoria, ou para mostrar o que o catálogo cobre.
| Name | Required | Description | Default |
|---|---|---|---|
| tipo | No | B2B para software de empresas, B2C para software de consumidores. Software que atende os dois entra nos dois. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine extra context beyond that: only categories with published software are returned and the result carries slug/tipo/count. It omits any ordering, pagination or size limits, which keeps it short of a 5.
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, zero filler: the first covers what is returned, the second covers when to use it. Purpose is front-loaded ahead of the routing guidance, and there is no redundant restatement of the title.
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 fields and the filtering constraint, which an agent needs to interpret results. Only ordering and pagination behavior are unmentioned, a minor gap for a small read-only catalog list.
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 'tipo' parameter has 100% schema description coverage including the B2B/B2C semantics and the dual-listing rule, so the schema does the heavy lifting. The description only restates 'tipo (B2B ou B2C)' and does not add filtering syntax or behavior for the parameter, matching the baseline 3.
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 ('Lista as categorias do catálogo') with the exact scope ('que têm software publicado') and the fields returned (slug, tipo, contagem). It also names the sibling it feeds into ('buscar_softwares'), so an agent can differentiate it from the other list/search tools without opening schemas.
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 two explicit use cases: retrieve the correct slug before calling buscar_softwares with a category filter, or show catalog coverage. The alternative tool and the condition that selects this one are named directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reclamações publicadas de um software, com a situação, as respostas do fornecedor e as mensagens, das mais recentes para as mais antigas.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug do software, como vem da busca ou do endereço softoteca.com.br/software/{slug}. | |
| pagina | No | Página dos resultados, a partir de 1. São 20 por página. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful behavioral detail beyond annotations by stating that results include status, vendor replies, messages, and are ordered newest to oldest, though it omits pagination 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?
The description is a single, front-loaded sentence that states the resource, included fields, and ordering without any filler. Every clause contributes relevant 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?
For a simple read-only listing tool with two fully documented parameters and safety annotations, the description supplies the key return content and ordering. It omits usage routing against similar sibling tools, but the schema and annotations cover the remaining practical gaps.
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%, so slug and pagina are already well documented in the schema, including the slug source format and page size. The description does not add parameter syntax or usage detail beyond the schema, making the baseline 3 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 identifies a specific resource, published software complaints, and specifies the returned content: status, vendor replies, and messages. It does not explicitly contrast with siblings like listar_avaliacoes, but the resource distinction is clear enough for an agent to select 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?
There is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as listar_avaliacoes. The ordering detail implies a listing use, but the description does not help the agent choose between similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Devolve a ficha técnica completa de um software do catálogo: cada campo com valor, origem e URL da fonte, planos e preços na moeda em que o fornecedor publica (reais, dólares ou euros, sem conversão), integrações, conformidade (LGPD, eSocial, NF-e e outros), fornecedor e categorias. Use depois de buscar_softwares, ou quando a pessoa citar um software e o slug for conhecido. Cite a url_canonica e a fonte_url de cada dado.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug do software, como vem da busca ou do endereço softoteca.com.br/software/{slug}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: prices are returned in the supplier's original currency with no conversion, each field carries origin and source URL, and the agent is instructed to cite url_canonica and fonte_url — a non-obvious output obligation.
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 what is returned, then how to trigger it, then the citation obligation — a sensible order. The field enumeration is dense but each item tells the agent what to expect, so little is wasted; the currency disclaimer 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 compensates by listing the payload contents and the no-conversion currency rule, plus the citation requirement. For a single-parameter read-only lookup, an agent has everything needed to call it correctly and report results.
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 single slug parameter is already well documented, including the softoteca.com.br/software/{slug} format. The description only echoes that a known slug is required, adding no new semantics about format or constraints; baseline 3 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?
States a specific verb and resource ('Devolve a ficha técnica completa de um software do catálogo') and even enumerates the returned fields — planos e preços, integrações, conformidade, fornecedor, categorias. This is clearly distinguishable from siblings like buscar_softwares or comparar_softwares 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?
Gives explicit sequencing ('Use depois de buscar_softwares') and an alternative trigger ('quando a pessoa citar um software e o slug for conhecido'). It does not explicitly rule out cases where comparar_softwares or alternativas would be the better choice, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Indicadores de um software a partir das avaliações e reclamações publicadas na Softoteca depois da moderação: nota geral, uso verificado, voltaria a usar, taxa de resposta do fornecedor, tempo da primeira resposta e índice de solução, nos últimos 12 meses e no histórico. Abaixo de 5, o indicador vem null (dados insuficientes). Use quando a pessoa perguntar se um software é bem avaliado ou se o fornecedor responde às reclamações.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Slug do software, como vem da busca ou do endereço softoteca.com.br/software/{slug}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds real context beyond annotations: data comes from post-moderation published content, indicators are reported for 12 months and full history, and any indicator with fewer than 5 data points returns null (insufficient data). This null-threshold rule is exactly the kind of behavior an agent needs to interpret results.
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 resource and its indicator list, then the null rule, then the usage trigger — a logical order with no filler. The field enumeration is long but earns its place by defining the exact return scope in 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, but the description enumerates the returned indicators and the time windows, and explains the null-condition interpretation. Combined with fully-covered input schema and complete annotations, an agent has everything needed to select and call this tool 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 description coverage is 100% and there is a single required 'slug' parameter whose format (search result or softoteca.com.br/software/{slug}) is fully documented in the schema. The description adds no further parameter meaning, so the baseline of 3 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?
States a specific verb+resource (obter_reputacao) and enumerates exactly what the indicator set contains: nota geral, uso verificado, voltaria a usar, taxa de resposta, tempo da primeira resposta, índice de solução. This clearly separates it from siblings like listar_avaliacoes/listar_reclamacoes, which return raw records rather than aggregated indicators.
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?
Explicit when-to-use trigger: 'Use quando a pessoa perguntar se um software é bem avaliado ou se o fornecedor responde às reclamações.' It gives clear intent-based context but does not name sibling tools or state when NOT to use it (e.g., when the user wants individual reviews, use listar_avaliacoes).
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.
buscar_softwares1 field changedInput schema / properties / preco_max_brl / descriptionPrevious value: -"Preço máximo em reais. Fica o software com plano gratuito ou com ao menos um plano de preço publicado até esse valor, na periodicidade do próprio plano (mensal, anual ou pagamento único)."New value: +"Preço máximo em reais. Fica o software com plano gratuito ou com ao menos um plano de preço publicado até esse valor, na periodicidade do próprio plano (mensal, anual ou pagamento único). O plano com preço em dólar ou euro não entra neste filtro: a Softoteca não converte."listar_avaliacoeslistar_reclamacoesobter_reputacaoestatisticas_da_categoriabuscar_softwares1 field changedInput schema / properties / origemAdded value: +{
+ "description": "Origem da empresa fornecedora: brasileira (sede no Brasil, comprovada no site do fornecedor) ou internacional (a filial brasileira de grupo estrangeiro conta como internacional). Fica de fora o software cujo fornecedor ainda não tem a origem comprovada; nas respostas, ele vem com fornecedor.origem null.",
+ "enum": [
+ "brasileira",
+ "internacional"
+ ],
+ "type": "string"
+}alternativasbuscar_softwarescomparar_softwareslistar_categoriasobter_fichaDiretório de dados de empresas brasileiras para agentes de IA.
Empresas de TI do Brasil por CNPJ ou domínio: porte, cidade, Fit e tecnologias (só dados públicos).
Preços, atas, contratos e sanções das APIs públicas de compras do governo brasileiro
Search, compare and price software tools. Verified prices with their date, real alternatives.
Add one secure layer between your agents and this server.