Prefeitura MT Cuiabá: NFS-e (Nota Fiscal Eletrônica de Serviços)

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

While annotations already mark the operation as idempotent and non-destructive, the description adds meaningful behavioral context: it distinguishes permanent non-expiring configuration from session-only login, and explains that calling with no args returns the login link. This goes beyond what annotations alone convey, though it does not discuss failure modes or return 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 compact and front-loaded with the core purpose. It uses a logical 'Best... Or...' structure to present two usage modes. Slightly more formatting could improve scannability, but every sentence contributes useful information.

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 simple one-parameter schema and helpful annotations, the description covers the main operational scenarios: no-args to request a link, token-based session login, and permanent header configuration. It could be more complete by noting what response the agent should expect after passing a token, but for this tool's complexity it is largely sufficient.

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 fully compensates for the single optional `token` parameter. It explains that the token is a JWT pasted from the browser, shows the exact call shape, and clarifies that omitting the argument returns the login link. This is excellent parameter-level guidance.

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 handles MCP.AI login for IDE agents and outlines the browser login/access-token flow. It is unambiguous about the action, though it does not explicitly contrast itself with sibling tools like 'connect' or 'marketplace', so it falls short of full sibling differentiation.

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 concrete usage guidance: the recommended permanent approach via `Authorization: Bearer <token>` header, the session-only alternative via { token: "<jwt>" }, and the no-args behavior to get the login link. It lacks explicit 'when not to use' or comparison with alternatives, but the practical guidance is clear and actionable.

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 readOnly and idempotent behavior. The description adds context by explaining the two possible outputs, which aligns with a non-destructive status check. It does not contradict the annotations and provides additional situational detail.

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, using two sentences to convey the core behavior and conditional outcomes. No unnecessary words 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?

Given no output schema, the description fully explains the return values (authenticated, pending array, connect URLs) and the conditions under which they appear. It provides complete context for an agent to know what to expect and when to call this 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 no parameters (schema coverage 100%), so the description does not need to explain any. The absence of parameters is consistent with a status-checking operation, and the description gives full clarity on what is returned.

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: 'Returns connection status and URLs.' It distinguishes from sibling tools like 'authenticate' and 'marketplace' by focusing on status checking, not authentication or other actions.

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 specific scenarios: when all providers are connected vs. when credentials are missing, explaining the output in each case. It implies this tool is for checking connection status, though it doesn't explicitly say when not to use it.

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?

Beyond the minimal annotations, the description discloses one-off invocation behavior, connect links for auth, checkout/top-up links for billing, the implicit install behind invoke, and workspace owner/admin requirements for writes. 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?

Long but appropriately structured with 'Core flow', 'KEY', and explicit scenario comparisons. Every sentence adds actionable detail, and the most important behavioral notes are 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 complex multi-action tool with no output schema, the description covers auth, billing, permissions, MCP vs prompt library separation, and install/invoke trade-offs. Minor gaps remain in exact response shapes and per-action parameter behavior, but overall it is highly 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 has 0% description coverage, so the description must explain parameters. It does explain the central action parameter and the roles of mcp_id, tool_id, and arguments, plus some prompt fields. However, many optional parameters like limit, immediate, tier_slug, cancel_reason, report_context, request_name/details, and prompt_targets are left undefined.

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 defines the marketplace as both a catalog and an execution platform, with a specific core flow (search → describe → invoke). It also distinguishes itself from sibling tools by emphasizing in-platform catalog/run capabilities and the prompt library 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?

Provides explicit guidance on when to use invoke vs install ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT'), and calls out report_bug, request_mcp, and list_tools as alternatives. The prompt library actions are also clearly separated from MCP actions.

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 declare read-only, idempotent, and non-destructive behavior, and the description adds useful context beyond these: payment per query, no platform credentials required, data is non-confidential, and LGPD compliance responsibilities. This enriches the agent's understanding without contradicting 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 paragraph and reasonably brief, but it includes legal disclaimers (LGPD) and hosting/payment details that are tangential to core usage. It is not overly verbose and front-loads the main purpose, though some content could be trimmed.

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 absence of an output schema and the complete lack of parameter descriptions, the description does not adequately explain what the tool returns or what inputs are required beyond their names. An agent would struggle to know what to pass for 'inscricao_municipal' or 'chave_identificacao', making the tool incomplete for practical 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?

The input schema has three required string parameters (inscricao_municipal, numero_nota, chave_identificacao) with zero description coverage. The tool description does not explain what these mean or how they map to an NFS-e query, leaving the agent without guidance on how to populate them.

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: querying NFS-e (electronic service invoice) from the official source of Prefeitura MT Cuiabá. The specific verb 'consulta' and resource 'NFS-e' distinguish it from sibling tools, which are generic platform utilities.

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 context about when to use it (to query official Brazilian sources) and notes it requires prepaid credit, but it does not mention alternatives or explicitly state when not to use the tool. It implies usage for NFS-e queries but lacks exclusion criteria.

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 provide some transparency (readOnly=false, destructiveHint=false, idempotentHint=true), but the description itself does not add any behavioral details beyond the instruction to include a conversation array. It does not disclose potential side effects or outcomes, though it does not contradict the annotations either.

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 information. It is well-structured and easy to read.

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 lacks sufficient detail for a complete understanding. It does not explain the purpose of 'context' or 'message', nor does it describe expected outcomes or error handling. The mismatch between 'array' and 'string' for conversation further reduces 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?

The description only explains the 'conversation' parameter (calling it an array of messages), but the schema defines it as a string, causing potential confusion. The 'message' and 'context' parameters are not described, leaving their meaning unclear. Coverage is low (only 1 out of 3 parameters referenced).

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. It identifies the action and resource, and distinguishes it from sibling tools which serve different 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 does not explicitly state when to use this tool versus alternatives. It only mentions what it does, leaving the user to infer the appropriate context without guidance on when not to use it or what other tools might be more suitable.

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 safety profile is clear. The description adds the minor detail that it reports 'current' versions, but this is consistent with the annotations and does not introduce additional behavioral context like side effects or permissions.

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, concise and free of unnecessary words. It directly conveys the action and the object of the action, achieving high readability and efficiency.

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 trivial complexity (no parameters, read-only, idempotent), the description adequately covers its behavior. The annotations provide additional safety context, and no output schema exists to require explanation of return values.

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 input schema has no parameters, and schema coverage is effectively 100% since no properties exist. With 0 parameters, the baseline is 4, and the description appropriately avoids mentioning parameters, as there are none to clarify.

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 show the current MCP platform and adapter versions. It uses a specific verb ('show') and a distinct resource ('current versions'), which distinguishes it from siblings like 'toolkit_info' that might provide broader system 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 offers no guidance on when to use this tool versus alternatives. It does not mention exclusions or explicitly compare to sibling tools such as 'toolkit_info', leaving the usage context implied rather than stated.

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 detail about what state is returned (installed MCPs, connection status, accounts, catalog tool counts). However, it does not describe any caveats like partial states or performance implications, which is acceptable for a simple read-only tool with strong annotations. The description supplements but doesn't over-explain.

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: 'Returns the current toolkit state: installed MCPs, their connection status, the accounts connected to each one, and how many catalog tools each exposes.' It conveys all relevant information without any filler, perfectly concise and structured.

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 parameters and no output schema, the description covers the key elements returned and implies it's a read-only state snapshot. It doesn't describe the exact structure or potential error states, but for a simple information tool, it's sufficiently complete. Sibling tools like connect or authenticate suggest context, and this tool likely serves as an overview, which is adequately described.

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 provides no information to enhance. The description effectively explains the return content, which is the only meaningful semantic information for a parameterless tool. Baseline of 4 is appropriate given no parameters require 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 function: 'Returns the current toolkit state' with specific elements listed (installed MCPs, connection status, accounts, catalog tool counts). This is specific enough to distinguish from sibling tools like 'show_version' or 'toolkit_info' isn't ambiguous. It lacks a comparative statement with siblings, but the verb and resource scope are clear.

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 information about when to use this tool versus others, no prerequisites, and no mention of context like needing to connect first. Sibling tools like 'connect' and 'authenticate' might be relevant but are not referenced. This is a bare functional description without usage guidance.

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