CADIN São Paulo

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

The description adds behavioral context beyond annotations: it explains the two invocation modes, the persistence of the config-based approach, and the session-only nature of pasted tokens. This complements the idempotentHint and aligns with the non-destructive nature, providing useful operational insights.

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 moderately sized paragraph with three sentences that all carry necessary information. It is not overly verbose, though the opening phrase 'MCP.AI for IDE agents' is slightly ambiguous. Every sentence earns its place, but the structure could be slightly more front-loaded.

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

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

For a simple authentication tool with a single optional parameter, the description covers the main usage scenarios and clearly distinguishes the two modes (config vs. session). It does not specify the response format for the token invocation, but given the simplicity and absence of an output schema, it is adequately 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?

The description thoroughly explains the token parameter: it is a JWT to paste, and the alternative of no args to get the link. This fully compensates for the 0% schema coverage, giving clear meaning to the parameter and its usage.

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: it provides a login link and accepts a JWT token for authentication, using specific verbs like 'log in' and 'call with'. It distinguishes the tool's role by explaining the config header method versus the session-only token method, making it distinct from siblings.

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: adding the token to the server config for a permanent non-expiring connection, or pasting it for a session-only login. It also explains the no-args call to get the link. However, it does not explicitly contrast with sibling tools like 'connect', which slightly reduces differentiation.

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 readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it is hosted without credentials, paid per query, and consults official credit bureaus. It also clarifies the client's responsibility under LGPD. While it does not describe the response format or rate limits, the additional payment and host details go 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 a concise three-sentence paragraph that front-loads the core purpose. The first sentence states what the tool does; subsequent sentences add payment, legal, and privacy context. It is appropriately compact without unnecessary filler, though it could be more structured for readability.

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 query tool with no output schema, the description covers the essential purpose, payment model, and legal basis. However, it omits parameter-specific guidance (especially the unusual required Cpf/Cnpj pair and the 'completo' flag) and does not describe what the response contains. Given these gaps, it is adequate but not fully complete for reliable invocation.

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

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

With 0% schema description coverage, the description should compensate for parameter meaning, but it does not. It mentions 'CPF ou CNPJ' generically, but the schema requires both Cpf and Cnpj, creating confusion about whether one or both must be provided. The 'completo' boolean parameter is entirely unexplained. This incomplete param semantics undermines correct invocation despite the overall purpose being clear.

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: to query the situation of a CPF or CNPJ in the CADIN registry of São Paulo's Treasury. It specifies the exact resource (CADIN) and distinct scope, which differentiates it from the platform-level sibling tools (authenticate, connect, etc.). Even without an explicit verb, the noun 'Situação' combined with the tool name 'consultar' makes the purpose unambiguous.

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

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

The description provides clear context for use: it is hosted on the platform, requires no credentials, and is paid for with prepaid credit. It also states a prerequisite (legal basis under LGPD). However, it does not explicitly mention when not to use it or name alternative tools, though the siblings are generic platform utilities. The legal and payment conditions give enough context to guide usage.

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 and idempotentHint. The description adds valuable behavioral details: it specifies the exact response in connected state (authenticated:true, empty pending[]) and in missing-credentials state (connect_url and per-install URLs). This goes beyond the annotations and helps the agent anticipate outcomes.

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: three short sentences that front-load the main purpose ('Returns connection status and URLs') and then provide conditional details. Every sentence contributes distinct information 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?

The description covers the two primary states (all connected vs. missing credentials) and mentions the return of URLs. It does not address partial connection scenarios or fully define what 'pending' contains, but given the simplicity and lack of output schema, it is sufficiently complete for an agent to understand the tool's behavior.

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 zero parameters and 100% schema coverage (empty schema), there is no parameter information to add. The baseline of 4 applies because the schema is complete and there are no parameters to explain.

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: 'Returns connection status and URLs.' It clearly distinguishes this from the sibling 'authenticate' tool, which likely performs authentication rather than reporting status. 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?

The description implies usage through conditional behavior ('When all providers are connected... When credentials are missing...'), which suggests when to call this tool. However, it does not explicitly state 'use this to check status before authenticating' or contrast with alternatives such as 'authenticate'.

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 reveals many non-obvious behaviors: 'invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list.' It also discloses auth and billing edge cases ('returns a connect link', 'checkout/top-up link... then you retry') and permission requirements ('require workspace owner/admin'). This far exceeds the annotations' basic 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 a massive single paragraph that packs in many details, flows, and edge cases. Every sentence adds value, but the lack of bullet points or section breaks makes it harder to parse. It is front-loaded with the core purpose, though the sheer length hurts conciseness.

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 multi-action tool with no output schema, the description is remarkably complete. It explains the main catalog flow, the install-vs-invoke distinction, authentication and payment fallback behaviors, the prompt library, and permission requirements. It even covers the shareable link behavior for published prompts.

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 coverage, the description must compensate for parameter meanings. It explains the central `action` enum and critical parameters like `tool_id` and `arguments` via the flow description ('describe returns one MCP's full profile... so you pick the right tool_id → invoke RUNS that tool'). However, several parameters (`tier_slug`, `immediate`, `cancel_reason`) are left unexplained, so it doesn't fully cover all 23 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 opens with a clear definition: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It then details the core flow (search → describe → invoke) and distinguishes itself from sibling tools by being the platform-wide catalog and runner.

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 usage guidance: 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use.' It also explains when to use each action: 'subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits.' This goes beyond simple context to give clear when-to/when-not-to direction.

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 provide readOnlyHint:false, destructiveHint:false, and idempotentHint:true, so the description adds limited behavioral context by mentioning the conversation array requirement. It does not disclose outcomes or side effects of submitting a report, such as ticket creation or system changes.

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 long, front-loaded with the primary purpose, and contains no redundant or extraneous wording. Every word 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?

Given the tool's simplicity (3 params, no output schema) and existing annotations, the description covers the main purpose and a key usage detail, but it omits the context parameter meaning and what happens after reporting. This makes it adequate yet incomplete.

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 conversation parameter (for reproduction) and implies the message content via 'report a bug, missing feature, or feedback', but it does not describe the context parameter at all, leaving a significant gap.

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 'Report a bug, missing feature, or send feedback' with a specific verb and resource, making the tool's purpose unambiguous. It is distinct from siblings like authenticate, marketplace, or show_version, so no confusion arises.

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 provides clear context on when to use the tool (for bugs, missing features, feedback) and instructs to include the conversation array for reproduction. However, it does not explicitly state when not to use it or name alternative tools, though siblings do not overlap functionally.

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 disclose the read-only, idempotent, and non-destructive nature. The description adds no further behavioral context, such as what happens on failure or the format of the version output. It simply restates the tool's action without adding value 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?

The description is a single, clear sentence that conveys exactly what the tool does with no unnecessary words or repetition. It is optimally concise and front-loaded.

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

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

For a simple, parameterless tool with strong annotations, the description is complete. It fully explains the tool's purpose without needing to detail parameters, return formats, or edge cases. There is no output schema, but the description sufficiently covers the tool's behavior.

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, so the baseline for this dimension is 4. The description has no need to explain parameters, and it doesn't attempt to, which is appropriate given the schema has no properties.

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: 'Show the current MCP platform and adapter versions.' It uses a specific verb ('show') and a specific resource (versions), and this distinguishes it from all sibling tools, none of which relate to versioning.

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 purpose is unambiguous and there are no sibling tools that could be confused with this one, so the context is clear. However, it doesn't explicitly state when to use or not use the tool, nor does it mention any alternatives, so it falls short of a 5.

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, providing a safe usage profile. The description goes beyond annotations by detailing what specific state information is returned (installed MCPs, connection status, accounts, catalog tool counts), which is useful context. No contradictions with annotations.

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

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

The description is a single, well-structured sentence that packs all necessary information without redundancy. Every clause adds value, and it is immediately clear what the tool does.

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?

This is a simple no-parameter tool with no output schema, and the description fully enumerates the return contents. It provides a complete picture of what the tool exposes, and there are no other operational details needed given the trivial 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 tool has zero parameters, and the input schema is empty with 100% schema description coverage. Per the scoring guidelines, a baseline of 4 is appropriate since the description doesn't need to explain 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 starts with 'Returns the current toolkit state' which is a specific verb and resource, and then lists the exact types of information (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes it from sibling tools like authenticate or connect, which perform actions rather than provide state information.

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 makes it clear this is a read-only informational tool, so an agent would use it when needing a status overview. It does not explicitly mention alternatives or exclusion criteria, but the context is unambiguous and there are no misleading signals.

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