Prefeitura RS Farroupilha: NFS-e (Nota Fiscal Eletrônica de Serviços)

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

The description adds meaningful behavioral context beyond annotations: it distinguishes between permanent (non-expiring) and session-only logins, and notes that calling with no args returns a link. It doesn't mention validation errors or side effects of permanent config, but given the idempotentHint annotation, this is sufficient.

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 verbose but well-structured: it opens with the purpose, then explains the two usage modes and the no-args fallback. Every sentence contributes useful information, though it could be tightened without losing clarity.

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 is reasonably complete. It covers the core authentication flows, return behavior (link), and integration context for IDE agents. It lacks error-handling details, but those are not critical for this tool's 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?

The input schema has one undocumented string parameter, but the description fully compensates: it explains the 'token' parameter is a JWT to paste for session-only login, and that omitting it retrieves a login link. This gives complete semantic meaning for a parameter that would otherwise be cryptic.

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 users for IDE agents by logging in through the browser and copying an access token. It distinguishes itself by explaining both permanent and session-only authentication flows, which aligns with its name and the sibling context (e.g., 'connect' implies a different action).

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 explicit instructions on when and how to use the tool: either by adding a token to the server config for a permanent connection or by pasting a token for a session-only login, with the option to call without arguments to receive a link. It doesn't explicitly mention alternatives or exclusions, but it provides clear usage context for the IDE agent scenario.

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 read-only and idempotent behavior, so the description adds value by detailing exact return conditions: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This goes beyond the structured metadata.

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 each sentence provides necessary behavioral detail without redundancy. It is concise and well-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?

For a simple read-only tool with no parameters and no output schema, the description fully covers the relevant behavior and edge cases (all connected vs. missing credentials). Annotations cover safety, and the description covers operational outcomes, making it 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 tool has zero parameters, and the schema covers 100% of them (vacuously). With no parameters to describe, the description needs no additional parameter information. Baseline for 0 params is 4, and the description satisfies this.

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: 'Returns connection status and URLs.' It specifies the behavior in different states (all providers connected vs. missing credentials) and distinguishes itself from sibling tools like 'authenticate' by focusing on status rather than action.

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 communicates when to use this tool by outlining the scenarios it handles (connected vs. missing credentials). It does not explicitly state 'use this to check connection status' or contrast it with alternate tools, but the context is clear enough for an agent to infer usage.

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 important behavior beyond the annotations: invoke runs tools one-off "without adding the MCP to the toolkit", credentials trigger a connect link, empty wallets trigger checkout, and writes require "workspace owner/admin." It also explains that search/describe flag installed states. No contradiction exists with the annotations, which are minimal; the description carries the transparency burden well.

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 densely packed and front-loaded with the core flow, but it is a long run-on paragraph with many concepts compressed together. The "KEY:" and "If..." clauses add necessary detail but could benefit from bullets or clearer segmentation. It is not wasteful, but it is heavier than ideal for an agent to parse quickly.

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 tool with 23 parameters and no output schema, the description covers the workflow, permissions, one-off execution semantics, prompt library behavior, and shareable links. It falls short only in not explaining output shapes for search/list_tools or a few minor parameters, but the overall operational context is substantially 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 does clarify the most critical parameters: action values are mapped to meanings, tool_id is tied to MCP profiles, and prompt_vars relate to filling {{variables}}. However, many parameters such as immediate, tier_slug, conversation, request_name, and cancel_reason are left unexplained, so the compensation is partial rather than full.

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 states exactly what the tool is and does: "the in-platform catalog of every MCP/tool, AND the way to run them." It goes further by enumerating each action's role (search, describe, invoke, install, list_tools, prompt library) and clearly contrasts with sibling tools like report_bug and toolkit_info. The multi-action nature is handled explicitly, so an agent knows this is the hub for MCP discovery, execution, installation, and prompt-library operations.

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?

Usage guidance is explicit and actionable: "prefer invoke for a single/occasional use" and "Use install only to make an MCP PERMANENT in the active toolkit." It also provides the core decision flow (search → describe → invoke) and explains when invoke returns a connect link or checkout link and how to handle them. This is excellent when-to-use versus alternatives 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description need not repeat safety. The description adds transparency about data access: it's the same data available to citizens, not confidential, and the client is responsible (LGPD). It also clarifies that payment is via prepaid creditchers, which is important for cost expectations. No mention of output format, but for a simple read operation, this is adequate.

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 four sentences, all providing relevant context (domain, payment, legal). It's not excessively long, and it's structured as: what it is, how to use it (payment), and data governance. It could be more concise, but it avoids fluff. The front-loading is acceptable with the main purpose stated first.

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 covers operational aspects (payment, credentials) and legal compliance (LGPD) which are useful, but it does not mention the response format or potential errors (e.g., invalid key, network failures). For a query tool with no output schema, this is a notable gap. It also doesn't mention any alternative tools for similar queries, though no sibling seems directly related.

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 parameter 'chave' with no description, and the tool description does not explain what 'chave' means (likely the NFS-e access key or number). Since schema coverage is 0%, the description does nothing to clarify the parameter. However, the domain context (NFS-e query) gives a strong hint that 'chave' is the service key, so it's not completely opaque, but still a gap.

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's a query (consulta) for NFS-e (Nota Fiscal de Serviços) in Farroupilha, RS, Brazil, and that it uses official sources. It doesn't explicitly name the tool's verb but 'consulta' implies retrieval, and the title includes 'consultar' (query). It identifies the domain (NFS-e) and the context (official Brazilian source).

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 operational guidance: it mentions prepaid credits, no platform credentials, and client responsibility under LGPD. However, it does not explain when to use this tool compared to alternatives, nor does it specify any particular prerequisites beyond having a 'chave' (key). The absence of usage examples or typical failure reasons leaves some 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 cover safety/idempotency, and the description adds that the conversation should be included for reproduction. It doesn't go into side effects or data handling, but no annotation 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?

Two short sentences, front-loaded with the primary action and then a useful usage note. No filler or repetition of schema details.

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 3-string-parameter tool, the purpose and reproduction hint are adequate, but the description omits the meaning of 'message' and 'context' and doesn't clarify how to encode the conversation. Thus it is minimally viable but incomplete.

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 only addresses 'conversation' and calls it an array while the schema type is string, missing the JSON-encoding nuance. The required 'message' and optional 'context' remain unexplained.

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?

Starts with a specific verb and resource: 'Report a bug, missing feature, or send feedback.' This clearly distinguishes report_bug from the sibling toolset and states a concrete action.

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 the tool: when the user wants to report a bug, missing feature, or provide feedback. It also gives an invocation hint about including conversation history for reproduction, though it doesn't mention exclusions or 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=true and idempotentHint=true, so the description need not repeat those. The description adds the specific object of the read operation ('MCP platform and adapter versions'). However, it does not disclose additional behavioral aspects like return format or error handling, so it only modestly extends 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, front-loaded sentence with zero fluff. Every word contributes to understanding the tool's function. It is an exemplar of conciseness without being under-specified.

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 version-checking tool with no output schema, the description is appropriate and complete. It communicates the core purpose and expected output (version numbers). It could have mentioned whether it returns a string or structured data, but that is not critical given the context and is easily inferred.

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 an empty schema, the baseline is 4 per instructions. The description adds no parameter-level detail (since none exist) but does explain what the tool does, which is acceptable. It does not need to compensate for missing schema info because there is none to miss.

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' and clearly identifies the resource ('current MCP platform and adapter versions'). It clearly distinguishes this tool from siblings like 'authenticate' or 'marketplace', and the scope ('current') adds precision. This meets the 5-point criteria of specific verb+resource and 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 usage context is implied by the nature of the tool (version lookup), but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It meets the 'implied usage' baseline but lacks the explicit alternatives seen in higher-scoring examples.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, giving the agent a clear safety profile. The description adds value by specifying WHAT state gets returned (MCPs, connection status, accounts, catalog tool counts) — going beyond the annotations with a concrete inventory of the tool's output content.

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 tightly-written sentences: the first states the core purpose, the second enumerates what's included. Zero wasted words — every phrase ('installed MCPs', 'connection status', 'accounts connected', 'how many catalog tools') earns its place by adding concrete detail.

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 info tool, the description fully covers the return value without needing an output schema. The enumeration of returned details (MCPs, statuses, accounts, catalog tool counts) is sufficient for an agent to decide which installed resource to query next. Slightly more context about output format or error cases could push this higher, but it's largely complete for the tool's 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?

Zero-parameter tool with 100% schema coverage by default, earning the baseline 4. The description needs no parameter explanation since none exist, and it properly front-loads the schema with an empty properties object.

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?

Description clearly states a specific verb ('Returns') plus resource ('current toolkit state') with explicit detail on what that state includes: installed MCPs, connection status, connected accounts, and catalog tool counts. Unambiguously distinguishes this informational tool from siblings like authenticate, connect, and 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 read-only nature and informational purpose are strongly implied by the description, but there's no explicit 'use this to' or 'use X instead' guidance. Sibling names suggest scenarios (e.g., authenticate for login, connect for adding resources) where this tool would be the wrong choice, but no exclusions or alternatives are stated.

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