Prefeitura SP São Paulo: Débitos de IPTU

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

Describes side effects of adding token to config vs pasting, and the behavior with no args; matches 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?

Concise two sentences with clear structure.

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?

Provides all necessary context for usage and parameter; no output schema needed.

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 token parameter is explained, including that it can be omitted.

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 states it's for authentication and distinguishes from sibling tools by describing the two modes.

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?

Explains permanent vs session usage and the no-args call to get the link.

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, destructiveHint=false. Description adds useful behavioral context: explains the state-dependent response (when credentials are missing vs when all providers are connected). This adds value beyond 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?

Two sentences, front-loaded with the primary purpose ('Returns connection status and URLs'). Every sentence adds value: the second clarifies conditional behavior. No 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?

Given no parameters, no output schema, and supporting annotations (readOnly, idempotent, non-destructive), the description is sufficient. It explains the return behavior in both states (authenticated vs missing credentials), which is the key contextual information an agent needs. Could mention how the connect_url is used, but not critical.

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% (none exist). Baseline for 0 params is 4. The description does not discuss parameters, but since there are none, it doesn't need to. It fully compensates by explaining the response scenarios.

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 what it does: 'Returns connection status and URLs'. It provides specific details about the return values for different states (authenticated:true, empty pending[], connect_url for toolkit and per-install URLs). Distinguishes from siblings by being the only tool that reports connection status.

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?

Implies when to use: when checking connection status or obtaining URLs for authentication. Does not explicitly mention alternatives or exclusions, but sibling tools like 'authenticate' suggest it's complementary rather than a replacement. No explicit when-not-to-use 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 description goes far beyond the annotations by explaining that invoke runs uninstalled MCPs one-off without bloating the tool list, returns connect links for missing credentials, returns checkout/top-up links when paid and wallet is empty, and that writes require workspace owner/admin. These are critical behavioral traits not visible in the annotations or schema.

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 dense paragraph rather than structured bullets, but every sentence earns its place given the tool's complexity. It is front-loaded with the core purpose and key flow, then covers exceptions, permissions, and the prompt library. Slightly more structure would improve scannability, but the information-to-length ratio is strong.

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 23-param, multi-action tool with no output schema, the description is remarkably complete. It covers the search-to-invoke lifecycle, the difference between invoke and install, auth/payment edge cases, permission requirements, installed status flags, and the prompt library sub-workflow. An agent has enough context to select the right action and handle expected failure modes.

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 by explaining the action parameter's role in the core flow and mapping actions to their purposes (e.g., describe returns full profile, invoke RUNS, publish_prompt returns a shareable link). It indirectly covers params like tool_id, mcp_id, prompt_slug, and report_context. However, it does not detail many other parameters such as arguments, immediate, tier_slug, conversation, and prompt_vars, leaving some semantics up to inference.

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: the in-platform catalog of every MCP/tool and the way to run them. It gives a specific core flow (search → describe → invoke), defines its role relative to capability requests, and distinguishes it from siblings by being the entry point for discovering and executing MCPs.

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 one-off use, use install only to make an MCP permanent, list_tools for what is currently callable, subscribe/cancel for billing, and report_bug/request_mcp for feedback/new MCPs. It also explains the action sequence and the prompt library as a separate use case, so an agent knows exactly when to engage 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 read-only, idempotent, and non-destructive. The description adds valuable context: it is hosted by the platform, requires no platform credentials, is a paid service with prepaid credit, queries official Brazilian sources, and includes LGPD data control responsibilities. This goes beyond annotations and informs the agent about payment and legal implications. No contradiction.

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 and front-loaded with the primary purpose, followed by operational details (payment, hosting) and legal considerations. It is not overly verbose, and each sentence adds meaningful context, though some sentences could be more tightly focused.

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 (1 parameter, no output schema, annotations present), the description covers the main purpose, payment model, data source, and legal responsibilities. It lacks explicit mention of the return format, but this is not critical for a simple query tool and is not contradicted by any schema or annotation.

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 required parameter 'cadastro_imovel' with no description (0% coverage). The description does not explain what this parameter is or how to format it (e.g., property registration number). While the name hints at its meaning, the description fails to compensate for the lack of schema details, leaving the agent to guess the expected input.

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: 'Débitos de IPTU, consulta em fonte oficial' (query IPTU debts from an official source). It specifies the verb (consultar/query), resource (débitos de IPTU), and scope (São Paulo), distinguishing it from generic sibling tools like authenticate or 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 implies when to use the tool (to query IPTU debts for a property in São Paulo), but it does not explicitly state when to use it vs alternatives, nor does it mention when not to use it. Since sibling tools are unrelated, differentiation is not needed, but there is no explicit 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 provide idempotentHint=true and destructiveHint=false, and the description adds context that the conversation array is needed for reproduction. It does not disclose broader behavioral traits like what happens after submission, but the bar is lower given annotations are present and there is no contradiction.

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: two sentences, both essential. The first states the purpose, the second gives a specific usage instruction. No wasted words 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 low-complexity tool with no output schema, the description provides the core purpose and the most important parameter guidance. It omits details about return values or error handling, but the simplicity of the tool and presence of annotations make it sufficiently complete for an agent to invoke 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?

With 0% schema description coverage, the description partially compensates by explaining the purpose of the 'conversation' parameter ('with recent messages for reproduction'). However, it leaves 'context' and 'message' semantics largely to inference from their names/defaults, so it does not fully cover all three 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 uses specific verbs 'Report' and 'send' with clear objects ('a bug, missing feature, or feedback'), expanding beyond the tool name. It clearly distinguishes itself from sibling tools such as show_version and marketplace by defining a broad feedback/reporting role.

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 an explicit usage instruction: include the conversation array with recent messages for reproduction. It sets clear context for when to use (reporting bugs, missing features, or feedback) and does not contradict any sibling tools, though it stops short of naming alternatives or exclusions.

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 well covered. The description adds minimal behavioral context beyond that, but it does clarify that it shows both platform and adapter versions, which is useful. 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, concise sentence that fully conveys the tool's purpose. It is front-loaded with the verb 'Show' and the resource 'versions', with no wasted words. It earns its place perfectly.

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 (no parameters, no output schema, clear annotations), the description is complete enough. It tells the agent what the tool does and what it returns (versions). The lack of output schema is not a gap because the description implies the return value. The tool is simple enough that this description suffices.

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 description coverage is 100% (vacuously). The description doesn't need to explain parameters since there are none. The baseline for zero parameters is 4, and the description appropriately focuses on the output rather than inputs.

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: showing current MCP platform and adapter versions. It uses a specific verb ('show') and resource ('versions'), and it distinguishes itself from siblings like 'toolkit_info' by focusing on platform and adapter versions rather than toolkit 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 implies usage context (when you need to check versions) but does not explicitly state when to use this tool versus alternatives like 'toolkit_info'. It lacks explicit exclusions or alternative recommendations, but the purpose is clear enough for basic 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?

Annotations already indicate readOnly and idempotent, so the description adds value by detailing the exact content returned (installed MCPs, connection status, accounts, catalog tool counts). It is consistent with annotations and introduces 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, concise sentence that lists all key output components without superfluous words. It is well-structured and directly conveys the tool's functionality.

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 of the tool and the absence of an output schema, the description provides a complete picture of what the tool returns. It names all relevant aspects of the toolkit state, leaving no ambiguity about its scope.

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 is fully covered. The description does not need to elaborate on parameters, and no missing information exists. The absence of any parameter discussion is appropriate and does not detract from completeness.

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: it returns the current toolkit state, enumerating specific components (installed MCPs, connection status, accounts, and catalog tool counts). This is distinct from sibling tools like authenticate, connect, or marketplace, so it unambiguously identifies 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 when to use it: when needing an overview of toolkit state. It does not explicitly mention alternatives or exclusions, but given its read-only nature and clear scope, the context is sufficiently clear for an agent to decide when to call it.

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