Suframa

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

Goes beyond annotations by disclosing two login modes (session-only vs permanent) and explaining that tokens are JWTs. It also notes that no-args returns a link. It does not mention potential side effects like token storage, but annotations already indicate idempotency and non-destructiveness.

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 three sentences, each adding distinct value (browser login, config option, session option). It is slightly verbose with the initial 'MCP.AI for IDE agents' context, but it is front-loaded with the core action.

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 one optional parameter and no output schema, the description covers the two invocation modes and the permanent vs. session-based distinction. It could mention what the returned link looks like or success/failure behavior, but it is reasonably 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 schema only lists optional 'token' with no description, but the description fully explains the parameter: a JWT to paste for session login, or omitted to retrieve a link. This 100% compensates for the lack of schema documentation.

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: logging in via browser and obtaining/using an access token for authentication. It differentiates itself as being for IDE agents and explains the token exchange process, though it doesn't explicitly contrast with sibling 'connect'.

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 usage guidance: call with no args to get a login link, or with a token for session-only login. It also recommends a permanent config approach. However, it does not explicitly state when to avoid this tool or compare it to 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 declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds meaningful behavioral detail beyond that: it explains the difference between fully connected (authenticated:true, empty pending[]) and missing credentials (connect_url, per-install URLs), which is not evident from annotations alone. This enriches the agent's understanding of expected 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 exactly two sentences, front-loaded with the core purpose. Every clause adds value: the first sentence states the general function, the second explains conditional outputs. There is no fluff or repetition.

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, the description covers the two most relevant scenarios: fully connected and missing credentials. It provides the key output fields (authenticated, pending, connect_url). A minor gap is the lack of mention of partial connection states, but overall the description is complete enough for a tool of this simplicity.

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 schema has no properties, so the description bears no responsibility to explain parameter meanings. The baseline for 0 params is 4, and the description adequately describes the tool's functionality without needing to compensate for parameter documentation.

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 then elaborates on two distinct outcomes (all connected vs. missing credentials), which clearly differentiates it from sibling tools like authenticate. The purpose is unambiguous and action-focused.

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 checking connection status, and the conditional output (authenticated:true vs. connect_url) gives context for when it would be relevant. However, it does not explicitly state when to use this tool instead of siblings like authenticate, nor does it mention any exclusions or alternatives. Usage guidance is inferred rather than explicit.

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 only provide basic flags (readOnlyHint=false, openWorldHint=true, etc.), but the description adds substantial behavioral context: invoke works even when the MCP is not installed without bloating the tool list, writes require workspace owner/admin, and specific responses include connect links or checkout/top-up links. This goes far beyond the annotations and no contradiction is present.

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 dense and well-organized, front-loading the core purpose and flow before diving into details. Every sentence carries useful information, and the structure (catalog flow, invoke vs install, permissions, prompt library) is logical. It could be trimmed slightly, but overall it earns its length for a tool of this complexity.

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 (multi-action dispatcher, 23 parameters, no output schema), the description is remarkably complete. It explains the search→describe→invoke flow, one-off execution semantics, permission requirements, billing/auth related responses, and the prompt library subfeatures. It also mentions return behaviors (full profile, prompt text, shareable links), covering the conceptual response landscape without an output schema.

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% and 23 parameters, the description must compensate. It does explain the core action parameter and the roles of mcp_id, tool_id, and arguments through the flow narrative. However, many parameters (e.g., immediate, tier_slug, cancel_reason, prompt_vars, prompt_targets) are not individually described, leaving gaps in semantic understanding for those less obvious fields.

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 official mcp.ai marketplace and execution platform, with a specific verb+resource framing: 'the in-platform catalog of every MCP/tool, AND the way to run them.' It distinguishes itself from siblings by enumerating its unique actions (search, describe, invoke, install, prompt library) and explaining the core 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 provides explicit when-to-use guidance, especially for invoke vs install: 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT in the active toolkit.' It also explains the decision flow (search → describe → pick tool_id → invoke) and conditions for connect/checkout links, giving clear context for choosing this tool over 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?

The description adds no behavioral context beyond annotations. It doesn't describe what happens after submission (e.g., whether a ticket is created, if a response is returned, or how idempotency works). With annotations providing only safety hints, the description should disclose more about the tool's behavior.

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 front-loaded, efficient sentences convey purpose and key usage instruction with no wasted words. The structure is ideal for quick agent comprehension.

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 sufficient for basic invocation but lacks information about return values or confirmation, which is not covered by an output schema. Given the tool's simplicity, it is adequate but has gaps in parameter semantics (context) and post-submission 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?

The description explains the conversation parameter as 'recent messages for reproduction,' adding meaning beyond the schema. However, it leaves 'message' and 'context' unexplained, relying on inference from the tool's purpose. Since schema description coverage is 0%, partial compensation is provided but not complete.

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 a specific action ('Report a bug, missing feature, or send feedback') and differentiates from siblings by being the only tool for user feedback. The purpose is unambiguous and action-oriented.

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 when-to-use scenarios (bug, missing feature, feedback) and a concrete instruction to include the conversation array for reproduction. It does not mention when-not-to-use or alternatives, but the sibling list makes it the obvious choice for this purpose.

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 cover readOnly, idempotent, and non-destructive behavior, so the description does not need to reiterate these. It adds no extra behavioral detail beyond the purpose, but it does not contradict 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 clear, substantive, and front-loaded. Every word earns its place with no redundancy or 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 zero-parameter, read-only version tool with strong annotations, the description is complete and sufficient. No output schema is needed for such a simple operation, and the purpose is fully disclosed.

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 input schema is trivially complete. The baseline for zero parameters is 4, and the description does not need to explain parameter semantics.

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 with a specific verb ('Show') and defined resource. It does not explicitly distinguish from sibling tools like toolkit_info, but the scope is sufficiently concrete.

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?

No explicit guidance is provided regarding when to use this tool versus alternatives. The simple, self-evident purpose implies usage for version checking, but there is no stated context or exclusion.

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 signal readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context: no credentials required, pay-per-query billing, public access data, and LGPD compliance responsibilities ('O cliente é o controlador dos dados'). This goes beyond the annotations by explaining billing and legal aspects, though it does not cover potential rate limits or response handling.

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 and front-loaded, with the core purpose in the first sentence. Subsequent sentences add useful context (hosting, credentials, billing, data privacy), but some legal phrasing (LGPD, 'O cliente é o controlador dos dados') could be seen as verbose relative to the tool's technical scope. Overall, it remains efficient 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 tool has no output schema, so the description should compensate by explaining the expected return value. It does not describe what 'situação' includes (e.g., status, registration details, legal documents) or how the 'completo' parameter affects results. The description covers data access and legal framing but leaves a significant gap in the response semantics, making it incomplete for an agent deciding on invocation details.

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 must compensate for parameter semantics. It only names 'CNPJ' as the input source but does not explain the 'completo' boolean parameter, nor does it specify CNPJ formatting or what 'completo' controls. The parameter meaning is largely left to inference from the parameter name alone.

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 a situação de uma empresa na Suframa (Zona Franca de Manaus) a partir do CNPJ' - a specific verb ('Consulta') + resource ('empresa na Suframa') + input method ('a partir do CNPJ'). This distinguishes it from sibling tools like 'authenticate', 'connect', and 'report_bug', which serve different platform functions.

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 operational context: 'Hospedado pela plataforma, sem credenciais, pague por consulta com crédito pré-pago' and clarifies the data is public. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites beyond the implied need for prepaid credit. The usage is contextually implied, not expressly guided.

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, covering safety expectations. The description adds useful context about the returned state details, going 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 sentence, front-loaded with 'Returns', and lists specific aspects of the toolkit state without any 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 simple, parameterless, read-only tool with strong annotations, the description fully covers behavior and return contents. No output schema is present, but the description itself sufficiently explains what the caller will receive.

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 baseline is 4. The description adds value by explaining what the tool returns, which is the only semantically relevant aspect.

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 enumerates the resource and content: installed MCPs, connection status, accounts, and catalog tool counts. This distinguishes it from sibling tools like connect 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 implies when to use the tool (to inspect toolkit state) without explicit exclusions or alternative mentions. However, given the distinct sibling tools, 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.