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 read-only, idempotent, and non-destructive behavior. The description adds the behavioral trait of pagination ('paginada'), which goes beyond the annotations, but does not elaborate on other behavioral aspects such as error handling or response format. It does not contradict 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?

The description is a single, concise sentence with a clear hyphenated explanation of the hierarchy. There is no redundant information or filler. It effectively communicates the core functionality and context in minimal 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 simple listing operation, the description is complete: it states the resource (brands), the scope (from the catalog), and key behavior (paginated). No output schema is provided, but the description does not need to explain return values for a basic list operation. The hierarchy context further enriches 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?

The schema provides 100% coverage with descriptions for all three optional parameters (`tipo`, `pagina`, `porPagina`). The tool description itself adds no additional parameter-specific semantics beyond what the schema already describes, so it remains at the baseline for high 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 that the tool lists vehicle brands from the Carpedia catalog, and explicitly places it as the highest level of the brand → model → version hierarchy, making its purpose unambiguous and distinguishing it from sibling tools like `carpedia_buscar_modelos` and `carpedia_buscar_versoes`.

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 when to use this tool (when you need brands at the top of the hierarchy) by mentioning the hierarchical level, though it does not provide an explicit contrast with alternatives. The pagination mention also hints at usage for large lists, but lacks a direct 'use this instead of X' statement.

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 description adds behavioral context beyond the annotations by mentioning 'paginada' (paginated), which is not covered by the readOnly/idempotent annotations. It does not contradict the annotations and provides useful information about the response behavior, though it does not elaborate on side effects or limits beyond pagination.

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 with no superfluous information. It effectively communicates the purpose and key input (brand slug) without unnecessary detail, making it well-structured and easy to parse.

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 the low complexity (three flat parameters, no output schema, clear annotations), the description is sufficient for an agent to understand the tool's purpose and usage. It does not need to cover output format or error cases for this simple read-only listing operation.

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% — all three parameters (marca, pagina, porPagina) have descriptions with examples and defaults. The tool description itself does not add extra meaning beyond the schema; it relies on the schema's parameter descriptions, 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 tool's function: 'Lista os modelos de uma marca do catálogo Carpedia' (lists the models of a brand from the Carpedia catalog). The verb 'Lista' and the resource 'modelos de uma marca' are explicit, and it is distinguished from sibling tools like carpedia_buscar_marcas (brands) and carpedia_buscar_versoes (versions).

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 stating 'a partir do slug da marca' (based on the brand slug), indicating the need for a brand slug. However, it does not explicitly mention when to use this tool over alternatives or provide exclusion conditions, so the guidance remains implicit rather than explicit.

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 and non-destructive behavior, so the bar is lower. The description adds behavioral context by explaining the two output-producing search paths and framing the tool as the fastest route to a fipeId; nothing contradicts 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 sentences, no filler, with the main purpose and fastest path front-loaded before parameter combinations. 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?

For a read-only lookup with three optional parameters and no output schema, the description covers both search modes and the intended result. It does not spell out the exact response fields or the no-argument edge case, but the annotations plus the usage modes are enough for an agent to call it 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%, so the baseline is 3; the description goes beyond it by explaining how the parameters combine (`termo` can be restricted by `marca`, while `marca`+`modelo` is the exact slug shortcut) and by giving concrete examples like 'corolla xei' and 'onix ltz'.

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 opens with a specific verb and resource ('Acha versões de veículo no catálogo Carpedia') and states the intended outcome ('chegar num fipeId'). This clearly differentiates it from sibling brand/model 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?

It explicitly presents two invocation modes: free `termo` search with optional `marca` restriction, or exact `marca`+`modelo` slugs to list versions. The guidance is clear for choosing parameters, though it does not name sibling tools or state when not to use this 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?

Adds details about null field meanings, 402 error when balance exhausted, and that it's API consumption not fuel. Annotations already indicate read-only and idempotent, but description enriches behavior 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?

Description is moderately long but each sentence adds useful context; no fluff or redundant padding.

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?

Covers all needed info: purpose, field semantics, null handling, error behavior, and external credit process. Sufficient for this simple read-only tool.

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?

No parameters exist; the schema is empty, so the description does not need to add parameter information. Baseline for 0 params is 4.

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 states it returns usage, quota, and balance of the connected account. Specifically distinguishes from vehicle fuel consumption and other 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?

Explains it is read-only, notes that no MCP tool exists for credit top-up, and implies when to check quota. Provides 'not for' guidance despite lacking explicit comparison to siblings.

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 description goes beyond the provided annotations by explaining the `rotulo` field that distinguishes full cost from IPVA-only, and clarifies that `estimativa` is always true. This adds behavioral detail and is consistent with the readOnly and idempotent hints.

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 moderately concise, containing three sentences with necessary clarifications. It is slightly verbose due to repeating the note about `rotulo` and `estimativa`, but remains focused and readable.

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 the absence of an output schema, the description adequately explains the output semantics (label values and estimate flag) and clarifies that depreciation is a statistical projection, not official FIPE data. This provides sufficient context for understanding the tool's behavior, though it lacks explicit use-case examples.

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 complete descriptions for all three parameters (uf, ano, fipeId). The tool description does not add additional parameter-level nuance beyond what the schema states, 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 that the tool estimates annual usage cost with specific components (depreciação, IPVA, combustível/energia) and differentiates from official FIPE tables. It does not explicitly name a sibling tool but the purpose is 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?

No explicit guidance is provided on when to use this tool versus siblings like carpedia_preco_fipe or carpedia_consumo. The description explains what it does but does not state selection criteria.

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 description adds meaningful behavioral context beyond the read-only/idempotent annotations: it explains conditional PBEV data ('quando há match auditado'), conditional photos ('quando existirem'), the proprietary size-classification methodology, the default effect of the `resumida` flag, and scope exclusion of maintenance plans.

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 the main purpose and uses compact, information-dense phrases to enumerate output content and conditions. It remains focused and does not include irrelevant details.

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 lookup with three documented parameters and no output schema, the description is complete enough: it lists the return content categories, conditional data availability, default response mode, methodology caveat, and a scope exclusion. An agent can accurately decide when and how to call it.

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 for parameters is already 100%; the schema descriptions for ano, fipeId, and resumida already provide the core meaning. The tool description largely restates the resumida behavior rather than adding new parameter-level meaning beyond 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 clearly states that the tool returns the technical data sheet for a version/model-year, including dimensions, engine, fuel consumption, PBEV-Inmetro seal when audited, size classification, and photos. It also distinguishes itself by explicitly saying it does not include the maintenance plan and by noting its own size-classification criterion rather than Inmetro's Annex D.

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 intended use is clear from the opening 'Ficha técnica de uma versão×ano-modelo' and the explicit exclusion of maintenance plans helps avoid using it for that need. However, it does not explicitly name alternative sibling tools or state a direct 'use X instead' comparison.

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 description adds a valuable caveat beyond the annotations: the depreciation projection is always marked as an estimate, based on Carpedia's own statistical model, not official FIPE data. This is critical for setting agent expectations. Annotations already declare read-only and idempotent behavior, so the description focuses on the estimate disclosure.

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 main purpose (historical series) and then adds the critical caveat about the estimate. It is efficient and contains no filler, though it packs several concepts together that could be slightly clearer if split.

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 explaining the return. It mentions the series, variation, and depreciation projection, which covers the key output components. However, it does not specify the time granularity (e.g., monthly, yearly) or the exact structure of the series, which could leave an agent uncertain about the response format. Given the tool's relative simplicity, this is acceptable but not fully complete.

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) are fully described in the schema with 100% coverage. The description references 'versão×ano-modelo', which maps to the parameters, but does not add additional format, constraints, or usage details 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?

The description clearly states the tool provides a historical FIPE price series for a specific version-year model, including variation and depreciation projection. This differentiates it from the sibling carpedia_preco_fipe, which likely provides the current price. The mention of 'versão×ano-modelo' ties directly to the parameters.

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 description: one would use this tool when needing historical price data or depreciation projections. However, there is no explicit guidance on when to prefer this over carpedia_preco_fipe or other siblings, and no when-not-to-use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds meaningful behavioral details: guaranteed renderable output, fallback logic, and AI-illustration attribution. This goes beyond the annotations without contradicting them.

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

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

Two sentences with zero filler. The first sentence front-loads the core purpose and fallback behavior; the second adds the guarantee, attribution policy, and prerequisites. Efficient and well-structured.

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 image-retrieval tool with three parameters and no output schema, the description covers the essential behavior, fallback logic, and attribution. It does not specify the exact return format (e.g., URL vs. binary), but given the simplicity and annotations, it is sufficiently complete.

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 all three parameters already have clear descriptions (slug format, year format). The description only reinforces the need for slugs but adds no new meaning beyond what the schema provides, so the baseline 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 it returns a vehicle image with a specific fallback chain (photo → logo → monogram). It identifies the resource (vehicle model via brand/model slugs) and is easily distinguished from sibling tools that handle specs, prices, or maintenance.

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 for retrieving vehicle images and explicitly requires brand/model slugs from the Carpedia catalog. It does not name alternatives, but among the 16 siblings it is the only image tool, so 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.

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 already state readOnlyHint=true and idempotentHint=true; the description adds conditional behavior about the returned data (all model years vs. one model year with variation), which is useful and does not contradict 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?

The description is short, direct, and well-structured in two sentences, with no redundant or irrelevant 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?

There is no output schema, but the description indicates what is returned in each mode. It could be slightly more complete by detailing the exact response structure, but it is sufficient for the tool's simple purpose.

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 covers both parameters with 100% coverage, and the description further explains the semantic difference between omitting and providing ano, enriching the parameter meaning beyond 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 first sentence clearly defines the tool's purpose: it returns the current FIPE price for a vehicle version identified by fipeId. The rest of the description clarifies the behavior with and without the ano parameter.

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 useful guidance on how to use the ano parameter (omit to list all model years, provide it to get a specific year plus variation), but it does not explicitly say when to choose this tool over siblings like carpedia_historico_preco.

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?

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description reinforces this by explaining it only queries status. It adds important behavioral details: it does not return the QR or copy-paste code, and it only accesses charges from the connected account. No contradiction with the annotations exists.

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

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

The description is somewhat verbose but each sentence adds useful information, such as status definitions, exclusions, and account scoping. It is well-structured and avoids irrelevant details. It could be slightly more compact, but the extra context is valuable.

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?

Since there is no output schema, the description compensates by explaining the possible status values and their meanings. It also clarifies what the tool does not return, which helps prevent misuse. A more explicit output format would increase completeness, but the status explanations are sufficient for typical usage.

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 sole parameter `id` has a clear description in the schema and is further elaborated in the tool description as the ID returned by the panel or POST /api/v1/creditos. Schema coverage is 100%, so the parameter meaning is well documented. The description adds enough context to make the input unambiguous.

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 checks the status of a Pix credit charge by ID, and explicitly distinguishes it from creation tools by noting there is no MCP tool to create charges. It also clarifies what statuses mean, making the purpose unambiguous. The sibling tools are all vehicle data tools, so this credit-status tool stands apart clearly.

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 explains when to use the tool: to check the status of an existing credit charge created via the panel or POST /api/v1/creditos. It also warns that the tool only sees charges from the connected account and that it does not return the copy-paste code or QR, which helps set expectations. It does not explicitly compare to sibling tools, but those are unrelated vehicle-data endpoints, so the usage context is still clear.

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 mark it as read-only, idempotent, and non-destructive, and the description does not contradict these. It additionally discloses important behavioral details like the segment-based ranking and the exact denominator field, providing full transparency.

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 dense but every sentence conveys a distinct, necessary fact. There is no redundancy or filler; the structure moves from general behavior to specific argument combinations, making it easy to parse.

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 compensates well by explaining the different result shapes for each argument combination and highlighting the denominator field. It is complete for a tool of this complexity.

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 descriptions cover all five parameters, and the tool description adds meaningful semantics: 'marca' alone returns totals, 'modelo' is only valid with 'marca', and pagination defaults are specified. This goes well 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 function: querying 0km vehicle registrations for a reference month. It distinguishes from sibling tools by focusing on sales/registrations data rather than specs, pricing, or consumption, and clarifies that the result depends on which arguments are passed.

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 explains the three invocation modes (no args, marca only, marca+modelo) and what each returns. Also clarifies the denominator scope and the model-based catalog link, leaving no ambiguity about when and how to use the tool.

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