Prefeitura SP Jundiaí: Certidão Tributária de IPTU

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

Description explains the behavior: it opens a browser login, copy token, and the alternative of providing a token directly. It mentions the token is a JWT and that permanent connection is non-expiring. Annotations show readOnlyHint=false (it's a mutation), but description does not contradict. It could add more about why the token is needed or what happens if no args are provided, but it's fairly 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?

The description is a single sentence but packed with information. It starts with the intended audience and purpose, then gives options. It's slightly long but every part is useful. The structure is front-loaded with the purpose.

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 authentication tool with one optional param and no output schema, the description covers the key aspects: how to use it (two ways), the context (IDE agents), and what to do. It doesn't specify return values, but since there's no output schema, it could mention what the tool returns (e.g., success message), but it's not critical for this flow.

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 has one optional parameter 'token' with no description. The description explains that 'token' is a JWT pasted by the user for session-only login, and that no args gets the link. This adds meaning beyond the schema, but still leaves some ambiguity (e.g., format, how to obtain). Given schema coverage is 0%, the description compensates partially but could be more precise.

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 for authentication, specifically logging in and obtaining an access token, with a distinction between permanent and session-only login. However, it doesn't explicitly name an alternative sibling tool, though 'connect' might be related.

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 when-to-use guidance: 'Best: add it to this server's config...' versus 'Or paste it here for a session-only login'. It also explains the two ways to call the tool (with token or with no args), and mentions the context of IDE agents, making usage context clear.

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 as false, so safety is well covered. The description adds useful behavioral detail by explaining the exact conditional response shape, including the pending[] field and provided URLs, which is useful beyond 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 long with efficient front-loading of the core purpose and then insightful conditional behavior. No word is wasted, and the key operational detail is immediately clear.

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 status tool, the description fully explains what the agent should expect in both connection states. Even without an output schema, this provides enough context for safe invocation and response interpretation.

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 there is no input ambiguity to resolve. The baseline of 4 applies because no parameter-specific documentation is 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?

Description states 'Returns connection status and URLs' with a specific verb and resource. It clearly differentiates itself from the sibling 'authenticate' tool by focusing on status inspection rather than authentication 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 gives clear conditional guidance: if all providers are connected the response shows authenticated:true and empty pending[], while missing credentials will return connect_url and per-install URLs. This provides enough context for when to use the tool, though it does not explicitly name alternatives beyond the implied authenticate 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 reveals important non-obvious behaviors beyond the annotations: invoke works even when the MCP is not installed, runs one-off without bloating the tool list, returns connect links for credential needs, and returns checkout/top-up links when paid MCPs have empty wallets. It also covers the hidden install behind invoke, permission requirements, and login-free prompt links. 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 dense and information-rich, front-loaded with the main purpose and structured around the core flow, key invoke behavior, permissions, and the prompt library. It uses long, packed sentences with semicolons and parentheticals that could be clearer as bullets, but every sentence earns its place given the tool's complexity.

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-parameter, 14-action multiplexed tool with no output schema and sparse annotations, the description is remarkably complete: it covers core flows, auth/payment edge cases, permission requirements, installed flags, and prompt library behaviors. It misses a few details such as the 'resume' action, 'immediate', and 'tier_slug', but not to a degree that undermines use.

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, and it does explain the action enum's semantics and several workflow inputs implicitly. However, many parameters remain undocumented: immediate, tier_slug, cancel_reason, report_context, request_details, prompt_targets, prompt_category, conversation, and others. The description adds value for the action parameter but leaves a meaningful gap for the rest.

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 opens with a clear, specific statement: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It then details the core search → describe → invoke flow, naming concrete capabilities and distinguishing this from sibling tools. The scope is broad but entirely 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 gives explicit usage direction: 'prefer invoke for a single/occasional use,' 'Use install only to make an MCP PERMANENT,' and 'request_mcp asks us to build a NEW MCP when nothing fits.' It also explains when to use list_tools, subscribe/cancel, and report_bug, and notes that writes require workspace owner/admin. This is strong when-to-use guidance with 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context: the pay-per-query credit model, that no platform credentials are required, that data is sourced from official agencies (same as available to citizens, not confidential), and LGPD controller responsibility. No contradiction — the query semantics align with the read-only annotation.

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?

Three sentences, front-loaded with the tool's purpose in the first sentence, followed by payment/credential context and data-legal framing. No redundant filler; each sentence contributes distinct information, though the middle sentence is somewhat dense with mixed topics.

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 (3 flat params, no nested objects, no output schema) with safety covered by annotations, the description handles purpose, payment model, data classification, and legal obligations well. But it leaves all parameter semantics unaddressed and says nothing about the returned certificate format, which matters more given the absent output schema.

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% for the 3 parameters (cpf, cnpj, inscricao, with inscricao required), so the description carries the full burden — but it never mentions any parameter, fails to clarify what 'inscricao' (IPTU registration number) means, and gives no guidance on choosing between cpf/cnpj/inscricao. This is a significant gap for a paid, binding query tool.

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 opening phrase 'Prefeitura SP Jundiaí: Certidão Tributária de IPTU, consulta em fonte oficial' states a specific action (query) and resource (IPTU tax certificate from Jundiaí's official source), clearly distinguishing it from the generic platform siblings (authenticate, connect, marketplace). It lacks an explicit verb in the subject line but 'consulta' conveys the operation clearly.

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 actionable context: 'pague por consulta com crédito pré-pago' (paid per query with prepaid credit) and 'sem credenciais da plataforma' (no platform credentials needed), plus the non-confidential, LGPD-governed nature of the data. However, it never explicitly says when to use this vs. alternatives or when not to use it, offering no 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 provide idempotentHint:true and readOnlyHint:false, and there's no contradiction. The description adds the behavioral note about including the conversation array for reproduction, which is helpful context. However, it doesn't disclose side effects, whether reports go to a specific system, or any success/failure messaging behavior. For a non-read tool, this could have done more.

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, zero waste. Front-loads the purpose statement, then adds the key parameter hint. Every sentence earns its place with no 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 simple feedback/reporting tool with 3 flat string parameters and no output schema, the description covers the essential elements: what to report and what to include for reproduction. It could mention what to expect after submission (e.g., 'no response is needed'), but the overall matrix is simple enough that this shouldn't be penalized heavily.

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 partially does — it explicitly explains the remote parameter ('conversation array with recent messages') and mentions the required message concept. However, the format/meaning of the 'context' parameter remains unclear, and the description doesn't fully compensate for the lack of schema documentation across 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?

Description uses a specific verb+resource combination: 'Report a bug, missing feature, or send feedback.' Clear about what it does but doesn't explicitly differentiate from siblings; the distinct taxonomy of sibling names (authenticate, connect, marketplace) makes the purpose understandable without further elaboration.

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?

Description implies when to use the tool (when reporting a bug/physical issue) but provides no explicit when-not-to-use guidance or named alternatives. The instruction to include the conversation array provides useful context about when this tool is appropriate.

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. The description adds no additional behavioral details beyond the straightforward 'show' action. Since annotations cover the key safety aspects, the description meets the baseline but does not go beyond.

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 extremely concise and clear, using a single sentence without any unnecessary words. It is perfectly sized for the simplicity of the tool.

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 no parameters and a simple output, the description fully explains the purpose. There is no need to elaborate on return values or additional context, so it is 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 no parameters, and the schema coverage is 100% (implicitly). The description does not need to explain parameters, and the baseline of 3 is appropriate given the high schema coverage.

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: showing the current MCP platform and adapter versions. It uses a specific verb ('show') and specific resource ('current MCP platform and adapter versions'), distinguishing it from sibling tools like authenticate or 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 no explicit guidance on when to use this tool versus alternatives. While it is a simple version check, there is no mention of scenarios or comparisons with sibling tools, so the usage context is implicit at best.

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 what information is returned, which is useful context but does not mention potential delays, caching, or any other behavioral nuance. It does not contradict 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, front-loaded with the primary action and outcome, and contains no filler or redundant wording. Every element (installed MCPs, connection status, accounts, catalog tool counts) is necessary to convey the tool's 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?

For a zero-parameter, read-only info tool with no output schema, the description sufficiently enumerates the return contents: installed MCPs, connection status, accounts, and catalog tool exposure. This covers the essential information an agent would need to decide when to call it and what to expect.

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 no parameters, so the baseline is 4. The description does not need to add parameter details, and none are provided.

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 the specific verb 'Returns' and clearly identifies the resource as 'current toolkit state' with enumerated details (installed MCPs, connection status, accounts, catalog tool counts). It effectively distinguishes itself from sibling tools like show_version, authenticate, connect, etc., which have distinct purposes.

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 its use for checking toolkit state but does not explicitly state when to use it over other tools or provide exclusions. Since siblings are functionally different, the context is clear enough, but there is no explicit guidance on when to invoke this tool versus alternatives.

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