CARF (Recursos Fiscais)

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

The description explains the behavior beyond annotations: calling with no args yields a link, calling with token authenticates. It clarifies the token format (JWT) and the distinction between permanent and session-only login, adding significant context to the high-level 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 slightly verbose but every sentence adds value, covering context, best practice, and alternative. The structure is logical, progressing from setup to invocation, though it could be tightened.

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 simple tool with one optional parameter and no output schema, the description covers necessary context: the interactive nature, two login modes, and how to invoke each. It is complete enough for an agent to execute 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?

With schema description coverage at 0%, the description fully compensates by explaining the 'token' parameter is a JWT and how to use it in both modes. It leaves no ambiguity about the parameter's meaning.

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: authenticating for the MCP server via a browser login and token. It provides the exact invocation pattern, distinguishing it from likely siblings by focusing on authentication flow.

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 explicit usage scenarios: best practice of adding the token to config for permanent access, and session-only login by pasting the token. It does not explicitly mention alternatives or when-not-to-use, but the two usage modes provide clear context.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context: no credentials required, prepaid credit payment, public data designation, and LGPD responsibility. This goes beyond annotations and gives the agent a clearer picture of operational and legal constraints.

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 reasonably concise at four sentences, covering the key operational aspects. The legal boilerplate about LGPD and data control adds length but is relevant for compliance. No redundancy or excessive detail.

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 gives a good high-level overview of the tool's purpose, access method, and data type. However, it lacks details on the output format, pagination, or what 'completo' does, and the CPF/CNPJ conflict with the schema is a gap. For a read-only query tool, this is adequate 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?

Schema description coverage is 0%, so the description must compensate. It mentions CPF/CNPJ as identifiers, but says 'a partir do CPF ou CNPJ' (from CPF or CNPJ) while the schema requires both fields. It also fails to explain the optional 'completo' parameter. This is misleading and incomplete for parameter understanding.

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: 'Consulta processos de uma pessoa ou empresa no CARF a partir do CPF ou CNPJ.' It uses a specific verb (consulta), identifies the resource (processos no CARF), and the input identifiers. It is distinct from the sibling system tools (authenticate, connect, etc.) which have unrelated purposes.

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 contextual usage guidance: 'Hospedado pela plataforma, sem credenciais, pague por consulta com crédito pré-pago' and clarifies it accesses only public information. It does not explicitly state when not to use the tool or name alternatives, but the context is clear enough for an agent to decide.

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 destructiveHint, so the bar is lower. The description adds behavioral context about the two return states (authenticated with empty pending[] vs connect_url when credentials missing), which is useful beyond 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 main purpose and efficiently explain both return scenarios. No 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 the tool has no parameters, no output schema, and strong annotations, the description is complete. It covers both primary states (all connected vs credentials missing) and what the caller should expect in each.

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?

There are zero parameters, and schema coverage is trivially 100%. The description correctly does not attempt to explain parameters. 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?

The description clearly states the tool 'Returns connection status and URLs', using a specific verb and resource. It distinguishes itself from siblings like 'authenticate' by focusing on status rather than performing authentication.

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 the tool (to check connection status) and explains expected states, but does not explicitly compare with alternatives like 'authenticate' or state when not to use it. Context is present but exclusions are missing.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses several non-obvious behaviors: null fields mean absence of information in the source, not a defect; zero results don't prove non-existence; and search operators (space, quotes, OR, minus) affect query semantics. This materially helps the agent interpret results and craft better queries.

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 compact but information-dense, with the core purpose and return fields in the first sentence, followed by logical caveats and usage notes. Every sentence adds value—none repeat the schema or annotations. The flow from purpose to follow-up tool to edge cases to parameters is well organized.

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 required parameter `termo` is thoroughly explained, the return shape is described, and edge cases (null fields, zero results) are covered. However, with no output schema and no property descriptions in the input schema, the lack of guidance on optional filters like date range and `tipo` leaves a moderate gap for an agent aiming to build precise queries. Still, the most essential call-time information is 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 description coverage is 0%, so the description must compensate. It does a good job for `termo` (full operator syntax) and `tribunais` (scope control), but it leaves `max`, `tipo`, `data_de`, `data_ate`, and `ordenar` unexplained. Since five of seven parameters are only documented by their schema names/types, the compensation is partial and the agent may guess at date formats or allowed `tipo` values.

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: 'Busca jurisprudência (acórdãos, súmulas, orientações jurisprudenciais, temas) por termo ou tese.' It lists the types of content covered and the output fields, making the tool's scope unambiguous. It also implicitly distinguishes itself from the sibling jurisprudencia_documento by noting that full texts are read with that tool, so an agent can tell search from retrieval.

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 clear guidance on when to use jurisprudencia_documento (when `texto_integral_disponivel: true`) and explains the effect of omitting `tribunais` (broad search). It also warns that zero results may indicate vocabulary mismatch or overly narrow filters. However, it does not explicitly address when to prefer sibling jurisprudencia_sumulas, so it stops short of a full when-to-use/alternatives matrix.

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 establish that the tool is read-only and idempotent, so the description's extra detail is useful rather than redundant: it explains that a result without id is not readable, that other decisions appear in outras_decisoes_do_processo, and that ids batch execution. No contradiction with the annotations; no harmful side effects are implied.

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 compact and front-loaded, with the core purpose stated first followed by precise usage rules. Every sentence adds information: input source, fallback behavior, multi-decision behavior, and bulk support; no wasted 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 read-only fetch tool with no output schema, the description covers the main inputs, fallback route, and expected response context (full text plus other decisions). The only real gap is the tribunal parameter, but the core invocation path is fully 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?

With 0% schema description coverage, the description must carry the parameter semantics, and it does for id (from a prior search result), numeracao (CNJ number), and ids (bulk). However, tribunal is never explained, and the relationship between numeracao and the CNJ number is only implicit, leaving part of the schema under-documented.

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-resource pair ('Lê o INTEIRO TEOR de uma decisão') and explicitly contrasts full text with the resumo, distinguishing it from the search-focused sibling jurisprudencia_buscar. The phrase 'não o resumo' removes ambiguity about what this tool does.

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

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

It states exactly when to call the tool: use the id from a jurisprudencia_buscar result with texto_integral_disponivel: true, or use the CNJ number. It also gives an explicit exclusion and fallback ('Resultado sem id não é legível por aqui, abra a url'), plus guidance for processes with multiple decisions.

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 destructiveHint. The description adds useful behavioral details beyond that: binding súmulas are included, full text appears in the 'ementa' when available, and cancelled/repealed súmulas are marked in the text. This adds real operational context without contradicting 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 dense sentences with no filler. The main purpose is front-loaded, followed by the sibling relationship and then useful output behavior. Every sentence earns its place.

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

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

For a simple two-parameter read-only search tool, the description is largely complete: it defines the query input, notes the fixed type, and explains key output behavior (ementa content and cancellation marking). It could elaborate on response format or max semantics, but the shortcut reference to jurisprudencia_buscar compensates for much of that missing detail.

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

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

Schema description coverage is 0%, so the description carries much of the burden. It clarifies 'termo' as the search keyword and implies the fixed 'tipo=Súmula', but it does not explain the 'max' parameter. The required parameter is clear, while the optional max remains only inferable from its name and number type.

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 action and resource: 'Busca SÚMULAS (incluindo vinculantes) por termo.' It goes further and explicitly distinguishes itself from jurisprudencia_buscar by declaring itself an 'Atalho' with a fixed 'tipo=Súmula', so there is no ambiguity about what it does or how it differs from the sibling tool.

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 clear usage context: it is a shortcut to jurisprudencia_buscar for Súmula-only searches, with 'tipo=Súmula' pre-applied. It does not explicitly state when not to use it or mention alternatives like jurisprudencia_documento, but the shortcut framing makes the intended scope reasonably 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?

The description goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=true) by detailing side effects and special cases. It explains that invoke runs a tool one-off even if not installed, returns connect/checkout links for auth/payment, and requires workspace owner/admin for write operations. It also notes how search/describe flag installed states and how the prompt library behaves. These are important behavioral traits not visible in 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, dense paragraph that front-loads the purpose well but then becomes a wall of text. While every sentence adds information, the lack of structure (bullet points, short sections) makes it harder to parse. It is not appropriately concise for an AI agent to quickly extract key facts.

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 tool's complexity (14 actions, 23 params, no output schema, no param descriptions), the description covers the core flow and important edge cases (auth, payment, permanent vs one-off usage) but omits details for some actions (e.g., resume) and many parameters. It gives a solid high-level understanding but is not fully complete for all possible invocations.

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 has 23 parameters with zero descriptions (0% coverage), so the description carries the full burden of explaining them. It mentions a few key parameters (action, mcp_id, tool_id) and the idea of arguments for invoke, but it never explains most parameters such as limit, query, immediate, tier_slug, conversation, cancel_reason, prompt_*, etc. Without per-parameter detail, an agent will struggle to construct correct calls.

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 clear statement: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' This immediately establishes the tool's purpose and scope. It also outlines the core search→describe→invoke flow, distinguishing it from sibling tools like authenticate or connect, which are narrow and focused on specific actions.

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 explicit when-to-use guidance, e.g., 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use.' It also enumerates what each action (search, describe, invoke, list_tools, subscribe, report_bug, request_mcp, search_prompts, etc.) is for, and contrasts invoke vs install. This gives an agent clear decision rules for selecting the right action within the 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=false and destructiveHint=false, so the agent knows it's a write operation but not destructive. The description adds value by mentioning the reproduction context (conversation array), but it doesn't disclose side effects, auth needs, or what happens after reporting. No contradiction 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 two concise sentences, front-loaded with the purpose and followed by a specific usage hint. Every word earns its place with no fluff or repetition of schema or annotation data.

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 3-parameter tool with no output schema and no nested objects, the description is fairly complete: it states the purpose and provides the key usage instruction. It could be slightly more complete by mentioning what happens after submission, but given the low complexity, it is mostly 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?

Schema description coverage is 0%, so the description must compensate. It explicitly explains the 'conversation' parameter ('recent messages for reproduction') and implies 'message' is the bug/feedback text. However, the 'context' parameter is left unexplained, and no details are given for data formats or defaults, so only partial compensation.

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: 'Report a bug, missing feature, or send feedback.' This uses a specific verb ('report') and resource, and is distinct from sibling tools like authenticate, marketplace, and show_version, which have different purposes.

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 clear context for usage by instructing to 'Include the conversation array with recent messages for reproduction,' which tells the agent what to include. However, it does not explicitly state when not to use this tool or refer to alternatives, though siblings are unrelated, so no exclusion is necessary.

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 the safety profile is covered. The description adds context that it reports platform and adapter versions, which is useful but does not disclose any additional behavioral traits beyond what the annotations imply. No contradiction.

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, clear sentence that directly states the purpose without unnecessary words or repetition. It is front-loaded and fully 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 zero-parameter, no-output-schema tool, the description is complete. It tells the user exactly what information will be displayed (MCP platform and adapter versions). The annotations cover safety, and there are no missing behavioral or usage details that would be expected.

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 has zero parameters, so the schema provides 100% coverage. The description adds no parameter information because none is needed. This meets the baseline for tools with no parameters.

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 with a specific verb ('show') and resource ('current MCP platform and adapter versions'). It is unambiguous and distinct from siblings like authenticate or connect, though toolkit_info might overlap, but the scope is explicit.

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 the tool is used to check versions, but it does not explicitly say when to use it versus alternatives such as toolkit_info. There is no mention of exclusions or conditions, but the simplicity of the tool makes the intended use obvious.

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 destructiveHint, covering the safety profile. The description adds value by specifying what exactly the state includes (installed MCPs, connection status, accounts, catalog tool counts), which is behavioral detail beyond the annotations. There is no contradiction 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, well-structured sentence that immediately states the purpose and lists the returned data components. No redundant words or filler; every part of the sentence carries 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?

The description is sufficiently complete for a simple, parameterless, read-only status tool. It enumerates the key return items, but does not specify the output format or mention potential error conditions. However, given the tool's simplicity and the existing annotations, this is adequate.

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 has no parameters, so there is nothing to describe. Per the rubric, a parameterless tool receives a baseline score of 4. The description does not need to compensate for missing parameter information.

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 with a specific verb ('Returns') and resource ('current toolkit state'), and enumerates exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling tools like show_version, which likely only returns version info.

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 clearly indicates the tool is used to retrieve an overall status snapshot. Although it does not explicitly mention alternatives or exclusions, the nature of the tool (a read-only state query) makes its usage context obvious relative to the sibling tools. No explicit when-not-to-use guidance is provided, but the context is unambiguous.

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