Carpedia

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

The description directly contradicts the annotation openWorldHint=false. The annotation implies a closed world (complete list), while the description states 'a ausência de um item na lista significa NÃO RASTREADO', indicating an open world (absence does not mean the item is not present). This is a serious inconsistency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two sentences with clear structure. It includes an important caveat about coverage and the possible statuses, without unnecessary verbosity.

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?

The description provides enough context for the tool's purpose and the meaning of absence, and mentions the statuses (serie, opcional, ausente). However, it does not describe the output format or structure, and the contradiction with the openWorldHint annotation detracts from completeness.

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?

Both parameters (fipeId and ano) have descriptions in the schema with 100% coverage. The tool description does not add any further semantic detail beyond what the schema already provides, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the resource (itens de série e opcionais de uma versão×ano-modelo) and the grouping by category. It does not explicitly distinguish from sibling tools like ficha_tecnica or resumo, but the purpose is specific enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. It mentions the open-world caveat about coverage, which is more about interpretation than usage context, and does not reference any sibling tool.

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 the full safety profile (readOnly, idempotent, non-open-world, non-destructive), so the bar is lower. The description adds relevant behavioral context beyond that: the result is paginated, and it clarifies that 'tipo' preserves the original FIPE type. It does not add pagination edge cases, but this is solid supplemental context.

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 the core purpose front-loaded and no filler. The hierarchy clause adds orientation value, though it is slightly beyond bare necessity.

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 paginated list tool with annotations covering safety and 100% schema coverage, the description covers purpose, pagination, hierarchy level, and filter semantics. Nothing critical is missing, though the shape of the returned brand list is left implicit (no output schema).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by enumerating the categoria domain and explaining the distinction between categoria and tipo ('tipo mantém o tipo original FIPE'). This helps the agent understand why both filters exist rather than just repeating 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?

States a specific verb and resource ('Lista as marcas de veículos do catálogo Carpedia') and pins its position in the hierarchy 'marca → modelo → versão', which implicitly separates it from siblings like carpedia_buscar_modelos and carpedia_buscar_versoes. An agent can identify what it returns 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?

The hierarchy note implies this is the entry point ('o nível mais alto'), and it clarifies how to use categoria and tipo, so usage is inferable. However, it never explicitly says when to use this versus the sibling model/version tools or states prerequisites, leaving the routing 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, covering the safety profile fully. The description's only extra behavioral claim is that results are paginated, which is already fully expressed by the pagina/porPagina schema fields, so it adds little beyond structured data without contradicting anything.

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 front-loaded sentence with no filler, and the required input is placed last where it reads naturally. "paginada" is mildly redundant with the schema's pagina/porPagina fields, keeping it just short of a 5.

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 list endpoint with fully described parameters and rich annotations, the description covers what the tool does and its input. With no output schema, it could say a word about what each model entry contains, but nothing essential to invoking 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 100% — marca's slug format and the pagination defaults/bounds are all documented in the schema. The description only restates that the brand is supplied as a slug, adding no syntax or format detail beyond the schema, 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 and resource ("Lista os modelos de uma marca") plus the scope ("do catálogo Carpedia"), so an agent can tell it apart from carpedia_buscar_marcas and carpedia_buscar_versoes by the level of the catalog hierarchy it addresses. It never names those siblings explicitly, so differentiation is inferable rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"a partir do slug da marca" implies a prerequisite (you need a brand slug, presumably from carpedia_buscar_marcas) and the model→version workflow is implied by the sibling set. However, there is no explicit when-to-use statement, no exclusion, and no named alternative, 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.

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds pagination behavior (10 per page) and the fipeId outcome, but does not explain what the response returns beyond pagination or error behavior for invalid slugs.

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-loads the purpose, then immediately states the two usage modes with parameter names. Slightly long but every clause carries routing information. Minor deduction for the parenthetical example interrupting flow.

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 search tool with full schema coverage and no output schema, the description covers purpose, the two invocation modes, pagination, and the fipeId goal. It does not describe return fields or how pagination metadata appears, but that is a minor gap given no output schema exists.

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 schema already documents every parameter including the enum, max lengths, and the marca+modelo dependency. The description reinforces the two modes and pagination size but adds no syntax or format detail beyond the schema. 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?

States a specific verb (Acha versões de veículo) and resource (catálogo Carpedia), and explains the outcome (chegar num fipeId), which differentiates it from siblings like carpedia_buscar_modelos or carpedia_buscar_marcas.

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 gives two usage modes with conditions: free search with `termo` (optionally narrowed by `marca`), OR exact `marca`+`modelo` to list versions of a specific model. This tells the agent exactly which parameter combination selects which behavior.

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 read-only/idempotent profile, and the description adds substantial behavior beyond them: every data-returning query debits the balance per the price table, insufficient balance yields HTTP 402, and `requisicoes_usadas: null` means measurement unavailable, not zero. It also pre-empts misreading legacy plan limit/reset fields as a cap.

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 core definition and the field semantics are front-loaded, and each sentence carries a distinct caveat rather than restating the name. It is dense with parentheticals and defensive warnings, making it heavier than an average zero-argument tool needs, but little is genuinely 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 parameters and no output schema, the description carries full burden and delivers: it explains the unit of `saldo_milesimos`, why zero does not mean empty, what legacy limit/reset fields do not mean, the cost per call, the 402 failure mode, and the null sentinel.

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 tool takes zero parameters, so there is nothing to disambiguate in the schema. The description instead spends its effort on returned-field semantics (milésimos units, welcome balance excluded), which is valuable but is not parameter documentation.

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 balance and month usage of the connected account) and names the exact fields involved. It explicitly rules out the biggest confusion risk in this sibling set: 'É sobre o consumo da API, NÃO sobre consumo de combustível do veículo', separating it from carpedia_custo_uso and carpedia_relatorio_consumo.

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?

Clear about the context of use (checking prepaid credit and monthly request volume) and states what the tool cannot do: there is no MCP tool to create or top up balance, directing the agent to the panel or API v2 instead. It does not explicitly route to/away from carpedia_status_credito or carpedia_lancamentos, which would have completed the picture.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world read), and the description adds substantial behavioral context on top: partial-sum semantics, the role of `faltantes`/`origens`, the `rotulo` cases and the risk of misreading "ipva_apenas" as cost of ownership, and that `estimativa` is always true because depreciation is a statistical projection, not official FIPE data.

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 definition, then progressively narrower caveats. It is long and dense, but nearly every sentence carries a distinct constraint; minor redundancy around the partial-sum caveats.

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 safety annotations, the description fully carries the burden: it explains the returned fields (`total`, `faltantes`, `origens`, `rotulo`, `estimativa`), their interpretation, and the edge case of out-of-scope vehicle types.

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 `uf`, `ano` and `fipeId` are already documented in the schema. The description only indirectly reinforces parameter meaning (UF determining IPVA and energy tariff), 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 computed resource and its exact composition: "depreciação projetada + IPVA da UF + combustível (ou energia, em elétrico)". It also clearly delimits itself against siblings such as carpedia_preco_fipe and carpedia_plano_manutencao by saying what it does not include.

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 states the applicable vehicle scope (only cars and light commercial vehicles) and the behavior outside it ("para moto, caminhão ou ônibus responde sem dado e sem cobrança"). It also names exclusions (no insurance quote, no full maintenance cost), but does not route the agent to a named alternative tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable behavioral details: missing fields mean 'not tracked' (not that the vehicle lacks the item), the resumida parameter changes output granularity, and photos appear only when they exist. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that front-loads the core purpose and then adds parameter details, exclusions, and data semantics. Every clause adds value, though it could be split into multiple sentences for readability. It is not overly verbose for the information conveyed.

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 tool with no output schema, the description fully specifies what to expect: content types, optional elements, the resumida switch, and the meaning of missing fields. It also points to methodology for the size classification and explicitly excludes maintenance plans, giving an agent everything needed to call it correctly and interpret 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 all parameters have descriptions. The tool description adds extra semantics for 'resumida' (default true, false gives full sheet) and clarifies the absence-of-data behavior, which the schema alone does not convey. This enriches parameter understanding beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states what the tool does: returns the technical sheet (dimensões, motor, consumo, etc.) of a version/year-model, plus official PBEV-Inmetro data when available, a proprietary size classification, and photos. It explicitly distinguishes from related tools by noting exclusions (maintenance plan) and clarifies the custom classification vs Inmetro's Annex D, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides strong usage context: it lists the exact contents, explains the resumida parameter's behavior, and explicitly states what is NOT included (maintenance plan), which helps an agent avoid misusing it. However, it does not explicitly name alternative tools or provide a direct 'use this when...' rule, leaving some inference to the agent.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the depreciation projection is explicitly flagged as a statistical estimate from Carpedia, not official FIPE data, which protects the agent from presenting it as authoritative.

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 front-loaded sentence with no filler; the parenthetical caveat is the one extra clause, and it earns its place by disclosing data provenance. Dense but not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, read-only history tool with no output schema, the description covers the essentials: what series is returned, that variation and a depreciation projection are included, and the caveat on the projection. Return-format details (granularity, pagination) are not addressed, which is a minor 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 description coverage is 100%, so the 'ano' format and the fipeId meaning are fully documented in the schema. The description restates the 'versão×ano-modelo' pairing but adds no format, edge-case, or syntax detail beyond what the schema already provides; 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?

States a specific verb+resource: the historical FIPE price series for a version×model-year, plus variation and depreciation projection. The 'série histórica' framing naturally distinguishes it from the sibling carpedia_preco_fipe (current price), but the description never names that sibling, so routing is left partially 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?

Usage is implied by the subject matter (an agent would infer 'use this when you need price history over time'), but there is no explicit when-to-use, no when-not-to, and no named alternative such as carpedia_preco_fipe for a snapshot price.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond them: the fallback chain, the guarantee that something renderable is always returned, and the attribution/AI-illustration labeling rule. Only the concrete return format is left unstated.

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, both front-loaded: the visual behavior and guarantee come first, the input contract second. No redundant filler and nothing that could be cut without losing meaning.

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 return-value burden and handles it well by describing the fallback content and attribution. The only notable gap is that the concrete image format/location (URL vs. inline) is not specified.

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 schema already documents each parameter; baseline is 3. The description adds value by synthesizing the either/or contract ('fipeId OR marca+modelo slugs from the Carpedia catalog'), making the grouping explicit rather than leaving it to be inferred from individual field notes.

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 the resource precisely ('Imagem do modelo') and even the fallback chain (photo → brand logo → monogram), so an agent immediately knows this returns a vehicle visual. It does not name a sibling tool to differentiate from, keeping it 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?

The description implies usage by describing the two accepted input modes (fipeId or marca/modelo slugs), but never says when to prefer this tool over siblings like carpedia_marca or carpedia_preco_fipe. Usage context is implied rather than stated.

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, closed-world), so the description's contribution is data-provenance semantics: every factual field carries a status, `estimativa` must never be cited as fact, `chegada.estado` may be null and `preco.v` is source text rather than a number. That is substantive guidance an agent would otherwise get wrong, especially 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?

Three dense sentences, front-loaded with the tool's scope and mode split, ending with the most consequential caveat. The semicolon-chained clauses and parenthetical lists make it slightly harder to scan than it needs to be, but 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?

With five optional parameters and no output schema, the description covers the modes, filters, and the interpretation of returned fields well. It does not describe the shape of list items versus the profile payload, leaving some uncertainty about what a list response contains, but the essential semantics 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 100%, so the baseline is 3; the description earns above that by spelling out what `slug` returns (ficha apurada, ficha prevista, comparativo, linha do tempo) and by reinforcing that `marca` and `status` apply only to list mode. Pagination parameters are left entirely to the schema, which is acceptable.

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 and its defining scope: vehicles that do not yet have a catalog page. It also distinguishes the two operating modes (single profile with `slug`, filtered paginated list without), which separates it from catalog-oriented siblings like buscar_modelos and ficha_tecnica.

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 between modes: pass `slug` for the full profile, omit it for the filtered list. It names the two filter dimensions (`marca`, `status`) and their meaning. It stops short of naming a sibling tool to prefer for already-cataloged vehicles, so no exclusion is stated.

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?

The annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful transparency by explaining that year fields may intentionally be null and what that null means, which helps the agent interpret results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no filler. It front-loads the core purpose and then adds a useful clarification about null year values without 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 simple one-parameter read-only tool, the description covers what the result contains and explains an important data nuance. It does not specify output format or behavior for unknown brands, but the given information is largely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes the single parameter 'marca' as a brand slug with examples. The tool description does not add additional parameter-level meaning beyond what the schema provides, so the baseline score 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 identifies the resource as an editorial brand entry and lists its contents (origin, founding year, Brazil arrival, operation status, summary, sources, confidence). It does not use an explicit retrieval verb like 'obtém' or 'retorna', but the intent is clear enough to distinguish from brand search 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 gives no explicit guidance on when to use this tool versus alternatives such as carpedia_buscar_marcas or carpedia_resumo. The content list implies it is for a single brand's editorial details, but no usage context or exclusions are provided.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description clarifies a key behavioral nuance: the absence of a marker in a grid row means 'not tracked' and not that maintenance is dispensable. It also explains that symbols and labels are exact replicas, which helps set expectations for output formatting.

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 main purpose and then adds important clarifications about output semantics. It is informative without being verbose, striking a good balance between detail and brevity.

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?

Given that there is no output schema, the description provides useful context about the expected output: sections in manual order, exact labels, and the meaning of missing km markers. This helps an agent anticipate the data structure and interpret results correctly, though it does not specify response format details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides clear descriptions for both parameters (fipeId and ano), covering 100% of them. The tool description does not add further parameter-specific details, so it aligns with the baseline for high schema 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?

The description clearly states the tool's function: providing scheduled maintenance per km for a version and model-year, with a specific focus on faithfully replicating the owner's manual. It distinguishes itself from other car-related tools by describing its exact output nature (manual replica) and unique semantics.

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 does not provide explicit guidance on when to use this tool versus alternatives. It explains output interpretation (e.g., km without mark means not tracked) but does not mention selection criteria or contrasts with sibling tools like maintenance-related or general car data tools.

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 declare readOnlyHint, idempotentHint, destructiveHint=false, so safety is covered. The description adds the conditional behavior (all years vs single year + variation), which is useful, but doesn't explain the return shape beyond 'variação' or note any limits. Good added context, not rich.

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 clauses, front-loaded with the primary output, zero waste. The conditional behavior is stated compactly and clearly.

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?

Given a simple read-only tool with full schema coverage and no output schema, the description covers the key behavioral branching. It lacks explicit differentiation from `carpedia_historico_preco` and `carpedia_resumo`, which would help an agent choose the right tool among many siblings.

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, including the special '32000' value. The description's mention of `ano` behavior is redundant with the schema, so 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 resource (FIPE price of a vehicle version) and the identifying key `fipeId`. Clear verb-less but precise noun+scope. It does not explicitly distinguish from sibling `carpedia_historico_preco`, which also deals with prices over time, leaving some ambiguity.

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?

Implies usage via parameter behavior (with/without `ano`), but gives no explicit when-to-use guidance or alternatives. An agent must infer that this is the current-price tool vs `carpedia_historico_preco` for past prices.

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 read-only, idempotent, and non-destructive traits. The description adds that the data is aggregated by day and route and restricted to a 366-day window, which is useful but does not reveal other behaviors like pagination, date boundaries, or timezone handling.

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, concise sentence that packs the essential information: subject, aggregation, and period limitation. No redundant words or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a report-style tool with no output schema, the description covers the main usage. However, it leaves ambiguity about what 'conta conectada' specifically refers to and does not hint at the nature of the returned data (e.g., units, structure). Still, it is reasonably complete for a lightweight query.

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 parameter descriptions only label 'inicio' and 'fim' as start and end dates. The tool description adds a significant constraint: the period must be within a maximum 366-day window. This enriches the parameter meaning beyond the basic 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 clearly states the tool's purpose: reporting usage of the connected account aggregated by day and route. The phrase 'Uso da CONTA conectada' distinguishes it from sibling tools like carpedia_consumo (vehicle consumption), and 'agregado por dia e rota' specifies the aggregation level.

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 does not provide explicit guidance on when to use this tool over alternatives. It only mentions a constraint (maximum 366-day window) but does not state scenarios for use or contrast with sibling tools such as carpedia_consumo or carpedia_resumo.

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 read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by stating the return is editorial text and explicitly excluding technical vehicle specifications, which helps set expectations 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?

Two concise sentences that front-load the tool's purpose and then give clear, scoped usage instructions. No filler or redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description adequately conveys the nature of the result ('editorial text') and what it does not contain (technical specs). It is complete enough for a simple read-only lookup tool, though it could mention potential response format or language.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes all three parameters with 100% coverage, including their roles. The description repeats and reinforces the fipeId-vs-marca+modelo distinction but does not add substantial meaning beyond what is already in the parameter 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?

Clearly identifies the tool as an editorial summary ('Resumo editorial') and distinguishes it from other Carpedia tools by noting it does not provide technical specifications. It also explains the two lookup modes (by fipeId for version, or by marca+modelo for model), making the purpose unmistakable.

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 explicit parameter usage: use fipeId for a version summary, or marca+modelo for a model summary. It implicitly differentiates from technical-spec tools by stating the summary is editorial and not technical, though it does not explicitly name alternative sibling tools.

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?

With readOnlyHint and idempotentHint already covering the safety profile, the description adds real behavioral context beyond annotations: the meaning of each status value (pendente/paga/cancelada/expirada), the negative scope that the copy-and-paste Pix code and QR are NOT returned, and the account-bound visibility limit. These directly prevent a caller from expecting payloads it will never get.

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 front-loaded with what the tool returns, then explains status values, then the negative scope — a logical progression with no filler. It is denser than strictly necessary (the creation-path caveat appears twice) but each clause carries 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 defining every status value and explicitly naming what is omitted from the response (copia-e-cola, QR). For a one-parameter read tool, an agent has everything needed to call it and interpret the result correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single well-documented `id` parameter, so the schema does the heavy lifting. The description restates the id's provenance (panel or POST /api/v2/creditos), which the schema already states, adding no new syntax or format detail. 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?

States a specific verb and resource — retrieves the state of a Pix credit charge by its `id` — with enough specificity (credit charge, connected account) that it is unmistakably distinct from the vehicle-data siblings. It stops short of naming a sibling to route away from, but no sibling covers this domain, so the ambiguity risk is low.

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 states the precondition that the charge must have been created outside this server (panel or POST /api/v2/creditos) and adds the exclusion 'sem ferramenta MCP para CRIAR cobrança', telling the agent this tool cannot create anything. That is exactly the when-to-use / when-not / no-alternative 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 declare the safety profile (readOnly, idempotent, non-destructive), and the description adds non-obvious interpretive context beyond them: position is WITHIN SEGMENT not market, the share/total denominator is the LEVES recorte (autos + comerciais leves) and not the whole market, and `denominador` carries the exact wording. The catalog link is stated to be by MODEL, never version. These caveats materially change how the returned numbers must be read.

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 in the first sentence, then the sentence-per-mode structure parses cleanly and every sentence carries information. It is dense but not padded; the only cost is that the mode cases are run together in prose rather than bulleted.

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 5-parameter, read-only stats tool with no output schema, the description covers all three invocation modes, the denominator caveat, the segment-vs-market distinction, and the model-level catalog linkage. Nothing an agent needs to call and correctly interpret the result 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%, so the schema already documents each parameter (baseline 3). The description goes further by explaining how parameters combine and interact — that `marca` alone yields brand aggregates, `modelo` is only valid with `marca`, and `grupo` is ignored in those cases — which is genuine added meaning over the per-field schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource (emplacamentos de veículos 0km) and then enumerates the exact output for each argument combination, so an agent knows precisely what the tool returns. It is clearly distinct from the sibling lookup tools (marcas, modelos, versões, fipe), which resolve catalog entities rather than registration 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?

It gives an explicit mode-selection map: no args = ranking, `marca` only = brand total/share/position, `marca`+`modelo` = model number and in-segment position. It also states that `grupo` is ignored when marca/modelo are supplied, removing the ambiguity an agent would otherwise resolve by trial.

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