Prefeitura MS: Calculadora de Fretes

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

Annotations indicate idempotentHint=true and readOnlyHint=false, but no destructive behavior. The description adds context about the browser flow, permanent vs session tokens, and the option of a header. However, it doesn't disclose details like whether the token is stored, rate limits, or what happens if invalid token is provided. The description complements annotations but doesn't go beyond them significantly.

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 paragraph but front-loaded with the tool's purpose and audience. It contains essential instructions in a clear sequence: log in, copy token, add to config or paste. It is moderately concise, though a bit dense with many instructions; could be structured into steps, but overall efficient.

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 covers usage scenarios adequately. It explains the permanent vs session options and the two call patterns. It lacks explicit error handling or security notes, but for an authentication tool, it's sufficiently complete. The context signals are minimal, so the description covers most needs.

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 parameter 'token' with no description. Schema description coverage is 0%, so the description must explain the parameter. The description explains that 'token' is a JWT the user pastes, and calling without args returns a link. This adds meaning beyond the schema, but is somewhat brief and does not detail token format beyond '<jwt>'.

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: authenticate the IDE agent to MCP.AI by logging in and providing an access token, either via server config or session token. It distinguishes the tool's role from siblings by its focus on authentication (vs connect, marketplace, etc.), although the sibling differentiation is not explicit.

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 when/how to use it: for login in the browser, getting a token, and either adding it to server config for permanent access or pasting it for session-only. It explains the two invocation modes (with token or without), but does not explicitly state when NOT to use it or mention alternatives (e.g., using 'connect' 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by detailing response shapes (authenticated:true, pending[], connect_url, per-install URLs). This provides meaningful behavioral context 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?

Two sentences front-load the main purpose and then provide conditional details. Every word is functional; no redundancy or filler. 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?

With no output schema, the description fully explains return values under the two relevant scenarios (all connected vs. missing credentials). Combined with annotations that cover safety, this is complete for a straightforward read-only status 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?

The tool has zero parameters, so schema coverage is effectively 100% and baseline for parameter semantics is 4. The description doesn't need to elaborate on parameters; it focuses on the return value conditions, 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 connection status and URLs, with a specific verb ('returns') and resource ('connection status'). It distinguishes from siblings like 'authenticate' by focusing on status checking rather than the auth flow itself.

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 implicitly provides usage context by contrasting conditions (all providers connected vs. missing credentials), guiding when to expect connect_url. However, it does not explicitly exclude alternatives or state 'use this to check status before authenticating,' so some inference is required.

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 is rich with behavioral detail beyond the annotations: invoke runs tools even when not installed, returns connect/checkout links under certain conditions, writes require workspace owner/admin, and search/describe flag installation state. These details substantially increase transparency and do 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 front-loaded with purpose and logically organized around the core flow, install behavior, writes, and the prompt library. It is dense and single-paragraph, but every sentence adds value; slightly more structure or formatting would improve scanability.

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 14-action, 23-parameter tool with no output schema, the description covers the primary flows, auth, billing, and prompt library very well. However, several relevant details are missing, such as the resume action and the JSON-string formats for arguments and prompt_vars, making the description incomplete 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?

Since schema description coverage is 0%, the description must compensate for the 23 parameters. It explains the central action values and core workflow, and touches on mcp_id/tool_id and prompt variables/slugs. However, it leaves many parameters undocumented, including how arguments should be formatted, immediate, tier_slug, cancel_reason, conversation, and limit, so the agent still has significant guesswork.

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?

Clearly identifies the tool as the official mcp.ai marketplace, the catalog of every MCP/tool, and the way to run them. It explains the core flow (search → describe → invoke) and distinguishes the tool from siblings like authenticate/connect/show_version by focusing on catalog discovery and execution.

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 guidance on when to use each action: prefer invoke for one-off/occasional use, use install only for permanent inclusion, use list_tools for what is currently callable, and request_mcp when nothing fits. It also explains when the user may need a connect link or checkout/top-up link, giving clear context for action 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?

The description adds transparency beyond the readOnlyHint annotation by mentioning that it queries official Brazilian sources, that data is not confidential, and that the client is responsible for data control under LGPD. It also notes the lack of platform credentials and prepaid credit requirement, which are useful behavioral details.

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 moderately concise but includes redundant legal boilerplate about LGPD and data control, which could be shortened. It conveys the essential information but could be more streamlined without losing meaning.

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 provides general context about the tool's purpose and payment model but omits crucial details such as what the output format is, how results are returned, or any error handling. Without an output schema, the description does not sufficiently round out the tool's behavior for a complete understanding.

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 lists five parameters (distancia, quantidade, data_prestacao, tipo_prestacao, tipo_transporte) with no descriptions. The tool description does not explain any of these fields, leaving their meaning entirely unclear. With 0% schema coverage and no additional context, parameter semantics are severely lacking.

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 is a 'Calculadora de Fretes' (Freight Calculator) for querying official sources, which distinguishes it from the sibling tools like authenticate or connect. However, it could be more explicit about the exact action (e.g., 'calculate' vs 'query').

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 some context about usage (e.g., no platform credentials, pay-per-query) but does not explicitly state when to use this tool over alternatives or give clear conditions for use. It implies a paid query service but lacks direct usage guidance.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context by advising that the conversation array should be included for reproduction, which implies the tool transmits diagnostic data. 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 extremely concise: two short sentences that state the main action and the single most important invocation detail. Every sentence earns its place, with no filler 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 simple reporting tool with 3 parameters and no output schema, the description covers the main trigger and the key reproduction hint. However, it does not explain the exact format of the conversation value, what happens after submission, or what the response conveys. It is adequate for a basic invocation but leaves some 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 carry parameter meaning. It explains that 'conversation' should contain recent messages for reproduction, but it does not clarify the required 'message' parameter or the optional 'context' parameter. Additionally, it calls the conversation an 'array' while the schema expects a string, which is potentially misleading.

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: 'Report a bug, missing feature, or send feedback.' This provides a specific verb and resource, and it distinguishes report_bug from the sibling tools, which are unrelated authentication, marketplace, calculator, version, and info tools.

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 clear context for when to use the tool: whenever reporting a bug, missing feature, or feedback. It does not explicitly mention alternatives, but the sibling tools are clearly unrelated, and the contexts are mutually exclusive. No exclusionary guidance is provided, but the intended usage 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'show' action is consistent with these. Since annotations are rich, the bar is lower, and the description adds the specific behavior of displaying platform and adapter versions. No contradiction exists.

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, concise sentence with no redundant words or fluff. It conveys the exact purpose without any unnecessary elaboration, achieving maximum conciseness for a tool of this simplicity.

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 simple (no parameters, no output schema), and the description adequately covers its purpose. While it doesn't specify the exact format of the version information returned, the absence of an output schema lowers the expectation, and the simple nature means the description is sufficient for a basic informational 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?

With zero parameters and 100% schema description coverage (vacuously), the baseline is 4. The description correctly implies no inputs are needed since it only shows existing version information. No parameter explanation is required given the absence of 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 'Show the current MCP platform and adapter versions' clearly identifies the verb (show) and the specific resource (MCP platform and adapter versions). It effectively differentiates from sibling tools like authenticate, connect, and report_bug by indicating a read-only informational purpose, and provides enough specificity to distinguish from 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?

The description implies usage when version information is needed, but it does not explicitly state when to use this tool versus the sibling toolkit_info or when not to use it. There is no explicit guidance on prerequisites or context, though the simple purpose makes the implied usage reasonably 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=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful detail on what the state includes (installed MCPs, connections, accounts, tool counts), enhancing transparency beyond the annotations. It does not mention performance or size concerns, but for its scope, it is well covered.

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. It starts with the verb 'Returns', specifies the object 'current toolkit state', and then lists the concrete details (installed MCPs, connection status, accounts, catalog tool counts). No filler or redundant phrasing. Perfectly 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?

Given zero parameters and no output schema, the description serves as the primary documentation of the return value. It thoroughly enumerates what the returned state contains, which is complete for the tool's purpose. The annotations cover safety, and the description covers content comprehensively. No 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?

The tool has zero parameters, so the description does not need to explain parameters. The baseline for zero params is 4, and the description avoids any irrelevant parameter talk while clearly stating the output. It adds no parameter descriptions because none exist, so a 4 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 verb

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 what the tool returns but does not specify when to call it relative to other tools (e.g., 'call before using market' or 'after authenticating'). While it is clearly a state-inspection tool, no explicit guidance on sequencing or prerequisites is given. For a zero-parameter info tool, this is adequate but not exceptional.

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