Prefeitura SP Sumaré: NFS-e (Nota Fiscal Eletrônica de Serviços)

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

Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description is not expected to restate those. It adds useful context beyond annotations by explaining the persistent vs session-only nature of the connection and the behavior with no arguments. It does not describe failure modes or exact return values, but the core login behavior is transparent.

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?

Every sentence contributes useful information, and the description is front-loaded with the audience and action. It is somewhat dense and could be broken into clearer steps, but there is no wasted content.

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 low-complexity tool with one optional parameter and no output schema, the description covers the key scenarios: permanent config token, session-only token, and no-arg link retrieval. No critical behavior is left unexplained.

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 coverage is 0%, but the description fully compensates for the only parameter: 'token' is explained as a JWT to paste for session-only login, and the no-argument behavior (get the link) is also described. This is exactly the semantic info the schema 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 states the tool's purpose: authenticating to MCP.AI for IDE agents via a browser login and access token. It gives a specific verb ('log in', 'call with token'), a resource ('MCP.AI'), and distinguishes this tool from siblings by focusing on authentication/token handling. The two modes (permanent config header vs session-only token) are 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 explicit usage guidance: 'Best: add it to this server's config as a header' for permanent access, or 'paste it here for a session-only login', plus 'with no args to get the link'. It clearly indicates when to use config vs the token argument, but does not explicitly discuss when not to use the tool or compare it to the sibling '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?

The description goes beyond annotations by revealing conditional return behavior and specific fields, which is not present in the structured data. It explains what happens in two distinct states, adding valuable transparency 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?

The description is two sentences long, front-loads the core purpose, and uses every word effectively. It is concise yet packed with specific conditional details, making it highly structured and scannable.

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 has no parameters and no output schema, the description covers the main scenarios adequately (authenticated vs. missing credentials). It is complete enough for straightforward usage, though it could theoretically mention error handling or edge cases, it is sufficient 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?

The tool has zero parameters, so the description need not explain parameters. The baseline of 4 is appropriate, and the description does not need to add anything more regarding 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 specifies 'Returns connection status and URLs,' using a clear verb and resource. It distinguishes this tool from siblings by focusing on status retrieval, and details specific return fields (authenticated, pending[], connect_url) that clarify its 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 implies usage for checking connection status but does not explicitly mention alternatives or exclusions. It provides clear context by describing conditional outputs (all connected vs. missing credentials), making the usage scenario understandable without explicit 'when-not' 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?

It discloses important behaviors beyond annotations: invoke runs tools without installing them, returns connect links for credentials and checkout links for payment, avoids bloating the tool list, and flags installed_in_toolkit vs installed_in_workspace. It also notes prompt share links open without login. No contradiction with the annotations 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 long but almost every sentence adds operational value—purpose, core flow, invoke exceptions, permission requirements, and prompt library are all covered. It is slightly dense and uses the Portuguese word 'pontualmente' mid-sentence, but it remains well front-loaded and organized by logical progression.

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 optional parameters, multiple action modes, and no output schema, the description covers the main workflows, permission boundaries, auth/payment edge cases, and the prompt-library subsystem. It omits some action-specific details like resume, immediate, and tier_slug, but the overall operational picture is strong enough for an agent to select and use the tool correctly in most scenarios.

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 compensates for the most important parameters by explaining action=search/describe/invoke, tool_id selection, arguments, and prompt_slug behavior. However, many parameters such as limit, immediate, tier_slug, conversation, cancel_reason, prompt_vars, request_details, and report_context receive no semantic explanation, leaving significant gaps.

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 the official mcp.ai marketplace, acting as both a catalog of MCPs and a way to run them. It names the core search→describe→invoke flow, distinguishes itself from the sibling report_bug tool, and covers both the MCP catalog and the prompt library with concrete example requests.

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 decision rules: use invoke for one-off runs, install only for permanent toolkit additions, list_tools for currently callable tools, request_mcp when nothing fits, and search_prompts for prompt text. It also states that writes require workspace owner/admin and explains the connect/checkout retry flow for auth and payment.

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 safety profile is covered. The description adds useful behavioral context about data being the same available to citizens, not confidential, requiring prepaid credit, and carrying LGPD data-controller responsibility. 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 contains redundant legal and platform boilerplate, such as repeated references to official sources and LGPD responsibilities, which could be condensed. Important operational information like the parameter is missing, so the length is not justified by content value.

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?

Despite low complexity (one parameter and no nested objects), the description omits essential parameter guidance and return value expectations. It covers payment, credential, and legal context, but not enough to fully support correct 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?

Schema description coverage is 0%, and the description does not mention the required 'codigo_autenticidade' parameter at all. It does not explain where the code comes from, its format, or how it should be supplied, leaving the agent without sufficient information to invoke the tool correctly.

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 a query/consulta for NFS-e (Nota Fiscal Eletrônica de Serviços) from Prefeitura SP Sumaré, using a specific verb and resource. This distinguishes it from the generic sibling platform tools 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 description provides clear operational context: it is an official-source query, requires no platform credentials, and is paid per query with prepaid credit. It does not name alternative tools or explicitly state when not to use it, but the use case is clearly implied and no conflicting alternative is present.

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 idempotentHint=true and destructiveHint=false, and the description adds the requirement to include the conversation array, which is a behavioral instruction beyond structured data. However, it doesn't disclose side effects like where the report goes or if it triggers any actions, so it only partially adds value.

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 mentions the key instruction. Zero wasted words, 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?

The tool is simple with 3 parameters and no output schema. The description covers the main use case and points to the necessary input but omits details like context field meaning, expected response, or any constraints. It's adequate for a basic tool but leaves room for clarification on 'context'.

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 explains the 'conversation' parameter (include recent messages for reproduction) but leaves 'context' and 'message' undefined. While 'message' is clear from purpose, 'context' remains ambiguous, leaving a gap in parameter understanding.

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 'report' and the resource (bug, missing feature, feedback). It distinguishes itself from sibling tools like 'authenticate' or 'connect' by its specific purpose of bug reporting, making it unambiguous.

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 (when there's a bug, missing feature, or feedback) and explicitly instructs to include the conversation array for reproduction. It doesn't mention when NOT to use it, but given the sibling tools are unrelated, this is 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description adds specificity about what is being shown (platform and adapter versions), which is meaningful 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, clear sentence with no filler and no redundancy. It fully conveys the tool's function without 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 zero-parameter, read-only version inspection tool with strong annotations, the description is complete. No output schema is required for this simple, informational operation.

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 extensive parameter explanation is unnecessary. The description fully covers what the tool does, and the schema confirms no inputs 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 uses a specific verb ('Show') and resource ('current MCP platform and adapter versions'), making the tool's purpose immediately clear. It distinguishes itself from sibling tools like authenticate/connect because it is specifically about version reporting.

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 is unambiguous and implies use when an agent needs to check the runtime platform or adapter versions. It does not explicitly state when not to use alternatives, but the use case is clear enough given the tool's simplicity and sibling 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 mark it as read-only, idempotent, and non-destructive. The description adds value by detailing exactly what the state includes (installed MCPs, connection status, accounts, catalog tool counts), which is beyond the annotations and helps the agent understand the output. No contradictions.

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 that immediately states the primary purpose ('Returns the current toolkit state') and then enumerates the specific components. Every word contributes to understanding, with 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?

Given no output schema and only read-only annotations, the description fully explains what the tool returns: the toolkit state with installed MCPs, connection status, accounts, and catalog tool counts. There are no parameters or side-effect details needed, making the description complete for an agent to use it correctly.

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 trivially 100% and no parameter descriptions are needed. The baseline for 0 parameters is 4, and the description doesn't need to add anything here.

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: returning the current toolkit state. It specifies the exact contents (installed MCPs, connection status, accounts, catalog tool counts), distinguishing it from sibling actions like connect or authenticate, which are operational rather than informational.

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: it is for retrieving state information. It doesn't explicitly mention when not to use it or alternatives, but the clear purpose and sibling tool names (e.g., connect, authenticate) provide enough context for an agent to choose this tool when needing status.

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