Cadastro PJ Básico

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

Annotations include idempotentHint=true and readOnlyHint=false. The description adds substantial behavioral context: explains permanent vs session-only authentication, how the login process works (browser, copy token), and the config-based approach. It doesn't contradict annotations and goes beyond them by describing the authentication workflow.

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 yet information-dense. The first sentence states the context and purpose, the next gives the recommended permanent solution, and the last covers the session-only alternative. Every sentence adds necessary detail 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?

Given the tool's simplicity (one optional param, no output schema), the description is complete. It covers all invocation patterns (with token, without token), explains both authentication methods, and the workflow is fully understandable. No gaps remain.

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 one optional string `token` with no description. The tool description fully compensates by explaining that `token` is a JWT for session-only login and that calling with no args returns the login link. This is essential meaning not present in 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 the tool's purpose: to authenticate the MCP server for IDE agents via browser login and token acquisition. It specifies the resource (authentication) and the action (log in, copy token), distinguishing it from sibling tools like 'connect' or 'marketplace'.

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?

Explicit usage guidance is provided: recommends the permanent config approach with `Authorization: Bearer <token>` header, and gives the session-only alternative using the `token` parameter, including behavior when called with no arguments to get the link. This is clear when-to-use and alternatives.

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 read-only and non-destructive. The description adds valuable transparency: no authentication needed, payment model (prepaid credits), public data nature, and LGPD compliance responsibility. 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?

The description is front-loaded with the core purpose, followed by necessary context about credentials, payment, and data privacy. It is slightly longer than strictly necessary due to LGPD phrasing, but each sentence adds meaningful context.

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

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

Given a simple lookup tool with no output schema, the description lists the returned fields (razão social, situação cadastral, natureza jurídica), and covers access, cost, and legal aspects. However, it omits behavior of the 'completo' parameter and any potential response differences, leaving a small completeness gap.

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

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

Schema coverage is 0%, so the description must compensate. It clearly identifies CNPJ as the input identifier, but the optional 'completo' boolean parameter is not explained at all. Partially compensates but leaves one parameter undocumented.

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: retrieving basic registration data (razão social, situação cadastral, natureza jurídica) from a CNPJ. It uses a specific verb ('consultar' implied) and resource (CNPJ), and the listed sibling tools are unrelated platform utilities, so it is well differentiated.

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 practical usage context: no credentials required, prepaid credit per query, and data is publicly accessible. It doesn't explicitly name alternatives or state when not to use, but given the sibling tools are generic, the context is sufficient for an agent to decide when to invoke 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing response behavior: returns authenticated:true and empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This enriches the agent's understanding of what to expect 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?

The description is two concise sentences, front-loaded with the primary purpose and followed by precise conditional details. Every sentence contributes to understanding the tool's behavior, with no redundancy or irrelevant content.

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 adequately covers the two primary states (all connected vs. credentials missing) and indicates the response shape. However, it does not address partial connection states (e.g., some providers connected, others not), leaving a small ambiguity. Given the tool's simplicity and no output schema, this is a minor gap rather than a critical omission.

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 of 4 applies. The schema already covers all parameter information (100% coverage with no properties), and the description does not need to explain any parameters. No additional parameter context is required.

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 ('Returns') and names the resource ('connection status and URLs'). It clearly distinguishes this from sibling tools like 'authenticate' by focusing on status retrieval rather than authentication itself. The two conditional outcomes are explicitly described, leaving no ambiguity about what the 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?

The description implies when to use this tool (checking connection status and getting URLs), but it does not explicitly state when to use it over alternatives like 'authenticate'. There is no direct recommendation or exclusion (e.g., 'use this before calling authenticate'), so context is only implied.

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

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

The description discloses significant behavioral traits beyond annotations: one-off invocation without installation, connect/checkout flows, permission requirements for writes, and the distinction between invoke and install. It also explains the prompt library's purpose. These details go well beyond the sparse annotations and add valuable context for selecting and invoking the tool safely.

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 long (~300 words) but appropriately so for a tool with 14 action modes. It is front-loaded with the core marketplace and runner concept, then the search→describe→invoke flow, then key nuances (one-off vs install, permissions, prompt library). Although dense, it is organized and each section adds necessary context; slightly more structured formatting would earn a 5.

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

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

With no output schema, the description must explain return values and behavior. It covers the main operational flows, including connect/checkout links and the distinction between installed vs one-off execution. However, it omits details on error handling, response formats for search/describe/list_tools, and edge cases like failed invocations. For a tool of this complexity, it's close 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 explains the key action values (search, describe, invoke, install, list_tools, prompt actions) and the roles of mcp_id and tool_id in the core flow. However, it does not systematically clarify the many other parameters (limit, query, immediate, tier_slug, cancel_reason, prompt_vars, etc.), leaving gaps that the agent must infer from defaults and names.

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 identifies the tool as the mcp.ai marketplace and execution hub, listing its core capabilities (search, describe, invoke, install, prompt library) and distinguishing it from sibling tools by explaining it as the central catalog and runner. It uses specific action-oriented language and covers the breadth of functionality.

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 guidance on when to use different actions: prefer invoke for one-off usage, use install for permanent addition, list_tools for currently callable tools, and request_mcp when nothing fits. It also explains the behavior of invoke with credentials and wallet, and indicates that writes require owner/admin permissions, effectively guiding tool selection.

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, destructiveHint=false, and idempotentHint=true, covering basic safety. The description adds behavioral context by directing the user to include the conversation array for reproduction, implying that a conversation history aids debugging. It also clarifies the tool supports three distinct report types (bug, feature, feedback), going beyond the title 'Report Bug'. 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 short sentences, both valuable. The first sentence states the purpose; the second provides a critical usage instruction. There is no repetition of the title or schema fields, and it is front-loaded with the action. 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 low complexity (3 params, no output schema), the description sufficiently covers the main use case. It explains the purpose and the key requirement (conversation array). However, it does not mention what the tool returns after reporting, nor does it explain the optional 'context' parameter. Still, for a simple feedback/report tool, the description is mostly complete, with only minor gaps.

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 directly explains the 'conversation' parameter as 'conversation array with recent messages', adding meaning beyond the schema's plain string type. The 'message' parameter is implicitly understood as the report content. However, the 'context' parameter is not addressed at all, leaving a gap. The description partially compensates but not fully.

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 action: 'Report a bug, missing feature, or send feedback', clearly identifying the tool's function and scope. It distinguishes itself from unrelated siblings (authenticate, connect, etc.) by naming the exact use case. The verb 'Report' and resource types are explicit, 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?

The description provides clear context for when to use this tool: whenever the user wants to report a bug, request a missing feature, or provide feedback. It also gives a specific instruction: 'Include the conversation array with recent messages for reproduction.' Though it does not explicitly name alternatives or exclusion criteria, the sibling tools are unrelated, so the usage 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, covering the safety profile. The description adds value by specifying exactly what versions are returned (MCP platform and adapter), which is not 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 sentence that is front-loaded and free of any wasted words. It conveys the entire purpose immediately and is appropriately concise for a zero-parameter version tool.

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 low complexity (no parameters), comprehensive annotations covering safety, and no output schema, the description adequately covers what the tool does and returns. Nothing crucial is missing for an agent to use 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?

The tool has zero parameters, so the schema provides no parameter semantics. The description doesn't need to explain any parameters, and with 0 params the baseline is 4. No parameter-related information is missing.

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' with a clear resource ('current MCP platform and adapter versions'). It is unambiguous and distinguishes this tool from siblings like authenticate and connect, which serve 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 no explicit guidance on when to use this tool versus alternatives such as toolkit_info. It is implied that this is for version checking, but no exclusions or context about overlapping tools are given.

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 the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context by detailing exactly what the state includes (installed MCPs, connection statuses, accounts, catalog tool counts), which is not derived from the annotations alone.

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 that states the verb and object first, then lists the key contents in a compact, readable manner. Every word earns its place with no 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 zero-parameter, read-only status tool with no output schema, the description thoroughly covers what the agent can expect to learn from calling it. It enumerates the main aspects of the toolkit state, making it complete for its intended 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 tool has zero parameters and an empty schema, so the description correctly focuses on the output rather than parameter details. With no parameters to document, the baseline score of 4 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 uses a specific verb ('Returns') and resource ('current toolkit state'), then enumerates the contents: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from siblings like show_version or authenticate.

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 implies this tool is for getting a snapshot of the toolkit's installed components and their statuses. It doesn't explicitly name alternatives or exclusions, but for a read-only status tool 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.