Receita Federal PER: DCOMP

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

Annotations already provide idempotentHint and non-read-only hints; the description adds meaningful behavior beyond that, such as the distinction between permanent config-based auth and session-only pasted tokens, and that no-args calls return the login link. It does not fully describe the result envelope or failure modes, but the added context is useful and not contradicted by 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 compact and front-loaded, packing all essential usage into a single informational paragraph. The mixed-language structure and "Best:" style is slightly informal, but no sentence is wasted and the content is directly actionable.

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

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

For a one-optional-parameter authentication tool with no output schema, the description covers the main paths: get link, paste token, and configure permanently. It could say more about what the response contains, but the provided behavior is sufficient for an agent to invoke the tool correctly in common situations.

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

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

Schema coverage is 0%, so the description carries the parameter burden. It explains that `token` is an optional JWT pasted by the user for session-only login, and that omitting it triggers a link-based flow. This is enough to make the parameter meaningful beyond the bare `string` type in the input 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 authenticates by providing a browser login link and accepting a pasted access token. It distinguishes the two main invocation modes (no args vs. token), making the purpose concrete, though it does not explicitly contrast with the sibling `connect` 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 explicit usage guidance: use the server config header for a permanent non-expiring connection, call with a pasted token for session-only login, or call with no args to obtain the link. It also explains when each approach is preferable, satisfying the when-to-use requirement.

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 behavioral context about the two possible response states (authenticated:true with empty pending[], or connect_url for toolkit and per-install URLs), which is valuable beyond the structured 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 sentences, front-loaded with the primary purpose, and every clause adds meaningful detail about the tool's behavior. No wasted words or 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 no-parameter, read-only status tool, the description explains the two primary response scenarios and their key fields (authenticated, pending, connect_url). It does not enumerate every possible field in the output, but given the simplicity and the lack of an output schema, it provides sufficient context for correct invocation and interpretation.

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 schema coverage is trivially 100%. The baseline for 0 parameters is 4, and the description adds nothing about parameters because none exist. No additional semantic detail is necessary.

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, and explicitly differentiates between two states (all connected vs. missing credentials). This is distinct from sibling tools like authenticate, which performs authentication rather than checking status.

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 context is implied: this is for checking connection status, while authenticate is for establishing it. However, no explicit when-to-use or when-not-to-use guidance or alternative names are mentioned, so it relies on the reader to infer the appropriate scenario.

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 (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) are sparse, so the description carries the burden and delivers richly: it discloses that invoke runs one-off without bloating the toolkit, that credential/login needs return a connect link and empty-wallet paid tools return a checkout/top-up link with retry, and that writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also clarifies install's permanent side effect (tools show up natively in future sessions). 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 content is dense and every sentence earns its place given the 14+ action scope, but it is presented as one giant unbroken paragraph with no line breaks, bullet points, or section headers for the three major domains (MCP search/run, billing/install, prompt library). The core flow is front-loaded well, but scannability suffers significantly for an agent parsing this at runtime.

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 high-complexity tool with 23 params, no output schema, and sparse annotations, the description covers an impressive amount: the discovery flow, install-vs-invoke semantics, auth requirements (owner/admin for writes), error recovery paths (connect link, checkout link + retry), the installed_in_toolkit vs installed_in_workspace flag behavior, and the prompt library mechanics. Gaps remain: the 'resume' action in the enum is never mentioned, and parameters immediate, tier_slug, and conversation are left undocumented.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the action enum's semantics well (invoke, install, list_tools, report_bug, request_mcp, search_prompts, get_prompt, publish_prompt, etc.) and conveys meaning for tool_id/mcp_id via the core flow. However, it does not systematically document many of the 23 parameters (immediate, tier_slug, conversation, prompt_tool, request_name, request_details, report_context, cancel_reason, cancel_comment, message, limit, query), leaving them only hinted via action context. Partial compensation only.

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 role as 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them' with a specific core flow (search → describe → invoke). It distinguishes itself from siblings (authenticate, connect, report_bug) by scoping to the marketplace catalog/runner. However, the purpose is diluted across 14+ action modes and the prompt library, so it's not a single verb+resource but a multi-purpose dispatcher.

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?

Excellent when/when-not guidance: 'invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off)', 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use'. It spells out the search→describe→invoke discovery flow, distinguishes the prompt library from MCP search ('search_prompts finds one... rather than MCPs'), and tells agents when to use list_tools, report_bug, and request_mcp. Explicit alternatives are named.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate that it's read-only. However, it adds useful context: it's hosted on the platform, requires payment with prepaid credits, and returns non-confidential official data. It also mentions LGPD data controller responsibilities. This adds behavior beyond annotations, but misses details like rate limits or response format.

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 long paragraph, moderately sized. It leads with the tool's purpose and then adds practical information about payment and legal compliance. It's not excessively verbose, but it doesn't use bullet points or short sentences, and some sentences are filler. It earns a passing score for being efficient enough.

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 tool has 3 optional parameters, no output schema, and useful annotations. The description covers the query purpose and payment model, but ignores what the output will look like (since no output schema exists), and it doesn't explain the parameter semantics. For a tool that queries official data, knowing the response structure is crucial, but it's not mentioned. It also doesn't mention any limitations or edge cases.

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

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

Schema coverage is 0%, so the description must explain the parameters. It mentions 'cpf', 'cnpj', and 'perdcomp' in the schema, but the description does not describe them at all. It only mentions 'consulta' and data sources. With three parameters and zero coverage, the description heavily undercompensates: it gives no clue as to what each param means, whether they are optional, or how they are used.

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 name is descriptive but opaque ('receita_federal_perdcomp_consultar'), and the description says 'DCOMP, consulta em fonte oficial' which clarifies it queries PER/DCOMP data from official sources. It lacks a clear verb+resource structure, but the phrase 'consulta informação de fontes e órgãos oficiais brasileiros' indicates it retrieves info. It does not distinguish from siblings, which are unrelated system tools, but purpose is somewhat clear.

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 the commercial context (payment with prepaid credits) and mentions it's the same data available to citizens, but gives no guidance on when to use this tool versus alternatives. It doesn't mention when to use it, when not to, or any prerequisites. Sibling tools are unrelated (auth, marketplace, etc.), so no differentiation is needed, but the description still lacks explicit usage 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 idempotentHint: true and destructiveHint: false, covering safety. The description adds behavioral context by instructing to include the conversation array for reproduction, which is useful. However, it does not describe any side effects, submission process, or return behavior, leaving some aspects undisclosed.

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 sentences, front-loaded with the core purpose, and contains no fluff. Every word adds value, making it concise 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 tool with 3 parameters and no output schema, the description is adequate but incomplete. It does not mention what happens after submission (e.g., whether a ticket is created) or explain all parameters. Since complexity is low, this is minimally acceptable but could be improved.

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, but it only explains the 'conversation' parameter (indicating it should contain recent messages). It does not explain the meaning of 'message' (likely the bug report content) or 'context'. This leaves two of three parameters underspecified.

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 verb and resource: 'Report a bug, missing feature, or send feedback.' This distinguishes it from sibling tools like authenticate or connect, none of which deal with issue reporting. The purpose is unambiguous and specific.

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 when to use the tool (reporting bugs, missing features, or feedback) without explicit exclusions. Since no sibling tool serves a similar function, additional 'when not to use' guidance is unnecessary. It does not mention alternatives, but the context is sufficiently 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that it reports both platform and adapter versions, but gives no further behavioral details such as output format or network access. This is acceptable but 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?

The description is a single, front-loaded sentence with no filler. It communicates the purpose in the fewest possible words without sacrificing clarity.

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 parameterless, read-only version-reporting tool with strong annotations, the description is complete. It tells the agent what the tool returns (platform and adapter versions) and no parameters or complex outputs require further explanation.

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 baseline is 4. The description does not need to document parameter behavior, and the schema coverage is complete for the empty parameter set.

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 uses a specific verb ('Show') and clearly identifies the resources ('MCP platform and adapter versions'). It is distinct from sibling tools like authenticate, connect, and marketplace, leaving no 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?

There is no guidance about when to use this tool versus alternatives. While the name and description imply it is for version checking, it does not state when this is appropriate or when another tool such as toolkit_info might be preferred.

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 the tool's non-mutating and safe nature. The description adds content detail (what the state includes) but no additional behavioral context such as staleness or error handling, so it relies on annotations for behavioral 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, front-loaded sentence with no redundant words. It efficiently conveys the tool's purpose and return content without fluff.

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 tool with no output schema, the description sufficiently enumerates the returned information (installed MCPs, connection status, accounts, catalog tool counts), and annotations cover safety. Given the simplicity and zero parameters, this is complete for an agent to understand and rely on.

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 and the schema is effectively empty with 100% coverage. The baseline for 0 params is 4; the description adds no parameter semantics because none exist, which 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 returns the current toolkit state, listing installed MCPs, connection status, accounts, and catalog tool counts. It uses a specific verb ('returns') and resource ('toolkit state'), distinguishing it from sibling tools like authenticate or connect which relate to setup.

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 use for obtaining an overview of installed MCPs and their connectivity, but does not explicitly state when to prefer it over alternatives like show_version or ensure prerequisites. No exclusions or alternative recommendations are provided, making the guidance 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.