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

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

The description explains important behavioral details: it supplies a login link when called without args, accepts a JWT for session-only authentication, and distinguishes permanent header-based config from transient token-based login. This context exceeds the basic idempotent/non-destructive 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 moderately wordy but every clause contributes useful guidance. The flow from permanent config to session-only token to no-args link is logically structured and compact enough 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 simple optional-parameter tool with no output schema, the description is complete: it tells the agent when to call witf token, when to call with no args, and what kind of result to expect. No critical invocation context is missing.

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 a single undocumented optional string 'token', and the description fully compensates: it specifies that the token is the JWT to paste and that calling with no args returns the login link. This is essential meaning the schema alone lacks.

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 explains the tool's purpose: authenticating MCP.AI users for IDE agents via browser login and token entry. It is specific about the authentication resource and flow, but does not explicitly distinguish itself from sibling tools like '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?

The description provides strong operational guidance: best practice is adding the token to config for a permanent connection, while pasting the token here is session-only. It does not, however, discuss when to use alternative tools or explicitly state when not to use this 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 and idempotentHint, so the bar is lower. The description adds valuable behavior context, explaining the authenticated field, pending array, and URL outputs in different states. This goes beyond the annotations without contradicting 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?

The description is two sentences, front-loaded with the core purpose, and every sentence adds specific behavioral detail. It is concise with no redundant 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 simplicity (zero params, no output schema), the description covers the key return states and URLs well. It could mention partial connection states or what pending[] contains, but it is sufficiently complete for a status-checking 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?

There are zero parameters, so the description does not need to explain any. Per the rubric, a zero-parameter tool receives a baseline score of 4, and the description appropriately omits 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 clearly states the tool returns connection status and URLs, using the specific verb 'Returns' and identifying the resource. It distinguishes itself from sibling tools like authenticate, which performs authentication, by focusing on status inspection.

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 context on when different outputs occur (all connected vs. missing credentials), implying this is for checking status rather than authenticating. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to decide 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.

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

While annotations are sparse (openWorldHint=true, destructiveHint=false), the description adds extensive behavioral context: invoke runs one-off without installation, returns connect links for credentials and checkout links for payment, requires workspace owner/admin for writes, and distinguishes installed_in_toolkit vs installed_in_workspace. No contradictions 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 a single dense paragraph but each sentence adds value—explaining the invoke-vs-install distinction, billing/auth links, and prompt library. It is front-loaded with the core purpose and the flow is logical. Although lengthy, the complexity of the tool justifies the prose.

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 breadth (14 actions, 23 params, no output schema), the description covers the primary flows (search→describe→invoke), auth requirements, payment/connect scenarios, installation semantics, and the promp library—far more than a typical tool. It anticipates edge cases (empty wallet, missing credentials) and explains return behaviors (connect link, checkout link), making it 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?

With 23 parameters and 0% schema description coverage, the description must compensate. It explains the role of 'action' and alludes to tool_id and arguments in the core flow, but leaves the majority of parameters (limit, query, message, prompt_vars, conversation, prompt_targets, etc.) unexplained. It gives meaning to the action enum but not to most fields, failing to bridge the coverage 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 establishes 'marketplace' as the central hub for discovering, describing, invoking, installing, and managing MCPs and prompts. It enumerates specific actions (search, describe, invoke, install, etc.) and distinguishes it from siblings by detailing the dispatch workflow. It is far from a tautology and provides concrete resource contexts.

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: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT', and explains that invoke works even for non-installed MCPs. It also differentiates subscribe/cancel, report_bug, request_mcp, and the prompt library actions, giving clear 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, so the description's additional disclosure of payment-per-query, no platform credentials needed, and LGPD data responsibility adds meaningful context beyond the structured fields. It does not contradict any 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 three sentences, front-loaded with the core purpose, then adds payment, data source, and LGPD context. It is compact enough, though it could arguably drop the LGPD mention and still be effective, but overall it is well-structured and not bloated.

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, the description explains the type of data (official Brazilian sources) and the payment model, but it does not specify what information will be returned or how parameters are supplied. For a paid consultation tool, this is a notable gap, though it covers the basic purpose and constraints.

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 4 parameters with zero description coverage, and the description does not explain any of them. While 'numero_nota' and 'codigo_verificacao' are somewhat self-explanatory from context, the tool fails to provide any semantics for 'cpf' and 'cnpj' or clarify formatting requirements, leaving agents without 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 queries NFS-e (electronic service invoices) from the official Salvador city source, using the verb 'consulta' with the resource 'NFS-e'. It distinguishes itself from siblings like 'authenticate' or 'marketplace' by specifying its exact domain and purpose.

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 clarifies that queries are hosted on the platform, require prepaid credit, and do not need platform credentials, but it does not provide explicit when-to-use or alternatives compared to other tools. Since siblings are unrelated utilities, the usage context is clear but lacks explicit exclusions or comparative 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 mark the tool as non-read-only, non-destructive, and idempotent, so the description only needs to add extra behavioral context. It adds the instruction to include recent conversation messages for reproduction, but it doesn't disclose what happens after submission or whether a confirmation is returned.

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 deliver purpose and the key usage note without repeating annotation or schema information. 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 simple and has no output schema, so the description covers the core purpose and the main optional input. It remains minimally adequate because it leaves the context parameter and any post-report behavior unaddressed.

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, but it only partly does so. It explains that conversation should contain recent messages and implies message is the report text, yet it omits the context parameter and calls conversation an 'array' while the schema types it as a string.

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 'Report a bug, missing feature, or send feedback,' which is a specific verb plus resource and is clearly distinct from unrelated sibling tools like show_version and marketplace. It goes well beyond the tool name alone.

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?

It provides clear context for when to use the tool: for bugs, missing features, or general feedback. It does not explicitly mention alternatives or when not to use it, but the sibling tools are dissimilar enough that the intended use case is evident.

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, covering the safety profile. The description adds the context that versions are 'current' (indicating real-time retrieval), but otherwise discloses no additional behavioral traits. This matches the baseline for annotation-covered tools.

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 no filler. Every word serves a purpose, making it highly efficient and easy to parse.

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 parameterless, read-only version query with no output schema, the description is complete. It states exactly what the tool reports (platform and adapter versions). No additional behavioral or output detail is necessary given the simplicity and rich annotations.

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 schema coverage is 100%, so the schema fully handles input semantics. The description adds no parameter information, which is appropriate since the tool takes no input. Baseline of 4 applies for parameterless tools.

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 uses specific verb 'Show' targeting 'current MCP platform and adapter versions', which is a precise and unambiguous resource. It clearly distinguishes from sibling tools like authenticate, connect, and marketplace by specifying exact content (versions).

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 purpose clearly implies use when version information is needed, and no exclusions or alternatives are needed for such a simple tool. However, it does not explicitly contrast with the sibling 'toolkit_info', which could potentially overlap. Still, the description's specificity provides sufficient context.

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 useful context about what the returned state includes (installed MCPs, connection status, accounts, tool counts), going beyond the annotations' safety profile. 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 a single sentence with the main verb and object front-loaded ('Returns the current toolkit state'). Every element listed (installed MCPs, connection status, accounts, catalog tool count) is meaningful and adds information without unnecessary 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?

Given no output schema and zero parameters, the description fully explains the semantic contents of the return value. It lists all relevant components of the toolkit state, making it adequate for an agent to understand what the tool provides. No significant gaps remain.

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 schema is trivially 100% covered. The baseline for 0 params is 4, and the description does not need to compensate for parameter documentation. No additional parameter semantics are needed.

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 the current toolkit state with specific content: installed MCPs, connection status, connected accounts, and catalog tool counts. This is a specific verb-resource pair and distinguishes it from action-oriented siblings like connect and 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 usage for inspecting toolkit state, but it does not explicitly state when to use it over alternatives or mention any exclusions. Since the purpose is self-evident and sibling tools are clearly different, the context is clear enough to warrant a 4 rather than 3.

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