Vínculos Societários

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

Annotations indicate a non-readonly, idempotent operation. The description adds context about the browser login flow and token handling, and explains the difference between permanent and session logins. It doesn't contradict annotations, but could be more explicit about side effects (e.g., opening a browser or the response after token submission).

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 longer than necessary but well-structured with a colon-separated series of alternatives. Each sentence adds useful information about authentication setup and invocation, though it could be condensed slightly.

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 no output schema, but the description explains the two call patterns and the concept of permanent vs session login. It omits details about the response format or error cases, but for a simple auth tool, the provided information is sufficient for an agent to select and invoke 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 schema provides no description for the optional 'token' parameter, but the description fully explains its meaning: passing a token enables session-only login, while omitting it returns a login link. This completely compensates for the schema's 0% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: authenticating IDE agents via browser login and token. It distinguishes itself by explaining the permanent config vs session-only login options, which differentiates 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?

Explicitly describes when to use the tool (to authenticate) and provides two alternative usage paths: adding token to server config for permanent access, or pasting token for session-only. It also instructs how to call with or without the 'token' argument, leaving no ambiguity.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral context by specifying conditional outputs: authenticated:true with empty pending[] when all connected, and connect_url when credentials are missing. This goes beyond annotations and helps set expectations without repeating them.

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

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

Two sentences, front-loaded with the core purpose. Every phrase earns its place, explaining both normal and missing-credential outcomes without any fluff. Excellent structure for quick parsing.

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 params, read-only status check) and lack of output schema, the description covers the main return states. However, it does not explain what pending[] contains when not all providers are connected or how partial connectivity is represented, which could be useful for full completeness.

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

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

There are zero parameters, and schema description coverage is effectively 100% (the schema has no properties). The baseline for 0 params is 4, and the description adds no unnecessary parameter detail, 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 it returns connection status and URLs, using specific verb 'returns' and resource. It distinguishes itself from the sibling 'authenticate' by focusing on status checking rather than initiating authentication, and describes key output conditions.

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

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

The description implies usage for checking connection status but does not explicitly state when to use this tool versus alternatives like 'authenticate' or 'toolkit_info'. There is no exclusion or direct mention of alternatives, leaving some ambiguity for an AI agent deciding between tools.

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

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

The description goes well beyond the sparse annotations (readOnlyHint=false, openWorldHint=true) by disclosing key behaviors: invoke works even when the MCP is not installed (one-off run without adding to toolkit), returns connect/checkout links when credentials or payment are needed, requires workspace owner/admin for writes, and distinguishes install vs invoke effects. This is rich, non-obvious context that annotations alone do not provide.

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 but every sentence contributes meaningful distinctions (invoke vs install, link flows, auth requirements, prompt library). It is appropriately sized for a multi-action tool, though it lacks bullet-point structure and could be better organized for scannability.

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 23 parameters and no output schema, the description covers the most critical flows: search/describe/invoke, install vs invoke, connect/checkout links, auth for writes, and the prompt library. However, it omits details on some actions (e.g., resume, subscribe specifics, report_bug) and does not describe general return value structures for search/describe.

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 is the primary source for parameter meaning. It explains the role of action, query, mcp_id, tool_id, and arguments through the core flow, and implies prompt-related params (prompt_slug, prompt_vars) for the library. However, some parameters like limit, immediate, tier_slug, cancel_reason, and request_details are not addressed, so it is not fully comprehensive.

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.' It then details the core flow (search → describe → invoke) and distinguishes it from siblings by centering on MCP discovery and execution, which is uniquely different from authenticate or toolkit_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?

Provides explicit internal guidance: 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use.' Also explains when to use report_bug, request_mcp, and prompt library functions. However, it does not contrast with sibling tools like toolkit_info or connect, so the when-not-to-use guidance across tools is 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?

Annotations already declare the tool is not read-only, not destructive, and idempotent. The description adds some context by explaining that conversation data aids reproduction, but it does not discuss side effects, permissions, or what happens after submission. This is sufficient given the annotations, 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 two sentences, front-loaded with the primary purpose and a single key instruction. Every word earns its place; no fluff 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?

The description is adequate for a simple reporting tool, but it omits meaning of the 'context' parameter and doesn't clarify that 'conversation' is a JSON-encoded string despite being called an 'array'. It also doesn't mention return values, but no output schema exists. These gaps make it minimally viable 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?

With 0% schema description coverage, the description must compensate for parameter meaning. It explains that 'conversation' should contain recent messages for reproduction, and 'message' is implied by the tool's purpose. However, 'context' is left undefined, leaving a required-optional parameter ambiguous. The compensation is incomplete.

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 specific verbs and objects: 'Report a bug, missing feature, or send feedback.' It also adds actionable context about including the conversation array for reproduction. This clearly distinguishes it from sibling tools like authenticate 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?

The description implies when to use the tool (when the user has a bug, feature request, or feedback) and provides a specific usage instruction: include the conversation array with recent messages. It does not explicitly mention alternatives or exclusions, but the sibling tools are unrelated, so the context is 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 and idempotentHint, indicating a safe read operation. The description adds what information is shown (platform and adapter versions) but does not disclose additional behavioral details such as network calls or return 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 sentence, front-loaded with the action 'Show', and contains no extraneous words or details. 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?

The tool is extremely simple with no parameters, no output schema, and annotations covering safety. The description sufficiently explains the tool's purpose without missing information necessary for 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?

There are zero parameters, and the input schema is empty, so the description needs to add no parameter meaning. The baseline for 0-parameter tools is 4, and the description correctly does not introduce unnecessary complexity.

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 shows the current MCP platform and adapter versions, using a specific verb 'show' and a specific resource. It is unambiguous and distinct from sibling tools like toolkit_info or report_bug.

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 when version information is needed, but it does not explicitly state when to use versus alternatives or any exclusions. There is no guidance comparing it to similar info tools like toolkit_info.

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. The description adds context about the specific constituents of the returned state (installed MCPs, connection status, accounts, catalog tools), which is useful but does not go further into potential side effects or usage limitations.

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 immediately states the core purpose and then lists the return content with no extraneous words. It is front-loaded and highly concise.

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 read-only info tool with no parameters and a strong annotation set. The description fully explains what the tool returns, which is sufficient for an agent to understand the tool's output. The lack of an output schema is mitigated by the explicit enumeration of return components.

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 0 parameters, so the schema fully covers them and the baseline is 4. The description appropriately does not need to explain parameter details.

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 the specific verb 'Returns' and clearly defines the resource as 'the current toolkit state', then enumerates the exact information provided (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes it from sibling tools like authenticate or report_bug.

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 when to use this tool (when the current toolkit state is needed) and no exclusions are given. It does not explicitly name alternatives, but the purpose is self-evident given the context of sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: no credentials required, prepaid credit cost, access to public official data, and LGPD compliance responsibilities, which go 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?

Three sentences, front-loaded with the main purpose and followed by access, cost, and legal context. No wasted words, though it is slightly longer than strictly necessary.

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?

Despite the schema lacking parameter descriptions and output schema, the description covers purpose, access method, cost, and legal obligations. It misses the 'completo' parameter and return details, but is reasonably complete for a simple lookup tool.

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

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

Input schema has 0% description coverage. The description mentions CPF or CNPJ but does not explain the 'completo' boolean parameter. Additionally, the phrase 'a partir do CPF ou CNPJ' conflicts with the schema requiring both CPF and CNPJ, creating ambiguity.

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 maps corporate links (vínculos societários) from CPF or CNPJ and shows participations and related partners, using a specific verb and resource. It is distinct from the unrelated sibling tools (authenticate, connect, etc.).

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

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

Provides usage context: hosted platform, no credentials, pay per query, and accesses public data. It does not explicitly contrast with alternatives, but siblings are unrelated, so the context sufficiently implies when to use it.

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