Prefeitura SP Campinas: Parcelas IPTU

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

Annotations indicate idempotentHint true and destructiveHint false. The description aligns: it's a login operation, can be called multiple times, not destructive. It adds behavioral info about session vs permanent config. It doesn't state side effects like clearing previous tokens, but that's minor. The description adds value beyond 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?

Two sentences but the first is quite long and packed with instructions. It's front-loaded with the main purpose 'log in in the browser' and then details. Could be slightly reorganized, but 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 the tool is an authentication helper with a single optional parameterUM, the description covers all relevant scenarios: browser flow, token paste, config header, and no-args link retrieval. It's complete for an agent to use 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?

Schema coverage is 0%, but the description fully explains the 'token' parameter: it's a JWT obtained from browser, and that calling with no args gives the link. This adds complete semantic meaning beyond the schema which just says '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 clearly states the tool's purpose: to authenticate for IDE agents like Cursor. It explains that it provides a login link or accepts a token, making the action unambiguous. It also differentiates between permanent config and session token usage, which adds clarity.

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: log in in the browser, copy token, optionally add to config as header, or call with token or no args. It also explains the difference between permanent and session login, so the agent knows exactly when and how to invoke 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, idempotentHint, and destructiveHint, covering safety. The description adds behavioral detail by explaining the two possible outcomes based on credential presence, including the return of authenticated, pending[], and connect_url. This goes beyond the annotations and provides useful context for expected outputs.

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 action ('Returns connection status and URLs') followed by conditional details. Every sentence provides necessary information without redundancy or filler, making it highly 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?

With no output schema, the description serves as the primary source for return behavior. It covers both main scenarios (all connected vs. credentials missing) and indicates key fields (authenticated, pending[], connect_url). While it doesn't detail the structure of URLs or pending array, this is sufficient for a simple status tool. The description is adequate but could be slightly richer.

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 zero parameters, and the description appropriately does not discuss parameters. With 0 params, the baseline is 4, and the description adds no extra meaning for parameters since none exist. It is not required to compensate for any schema 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's action: 'Returns connection status and URLs.' This is a specific verb ('returns') and resource ('connection status and URLs'), and it distinguishes from siblings like 'authenticate' by focusing on status rather than authentication. The additional details about output states further clarify the 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 state when to use this tool versus alternatives. It lacks guidance on when not to use, such as pointing to 'authenticate' for establishing connections. The context is clear but not explicit about exclusions or alternate tools.

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 critical behavioral traits beyond annotations: it states that writes require workspace owner/admin, that invoke runs an MCP one-off without installing it, and that invoke returns connect/checkout links for auth/payment. This adds substantial context beyond the sparse annotations (no readOnlyHint, openWorldHint only) and covers side effects, prerequisites, and retry logic.

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 thorough and well-organized, starting with the main purpose, then core flow, then edge cases, then additional actions, and finally prompt library. However, it is quite long and dense, covering many sub-actions in a single paragraph. While every sentence carries information, it could be more concise by separating actions into bullet points or summarizing less critical details. It is not wasteful but is longer than necessary.

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 complexity (multiple actions, 23 parameters, no output schema), the description is highly complete. It explains the search/describe/invoke flow, install vs invoke tradeoffs, auth/payment handling, permission requirements, and the prompt library sub-tools. It does not explain every parameter, but it covers all major workflows and expected outcomes, making it sufficient for an agent to 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?

Schema description coverage is 0%, and with 23 parameters the description must compensate. It explains the core action parameter and key parameters like mcp_id, tool_id, and arguments within the flow context, but it does not systematically document many other parameters (e.g., limit, conversation, report_context, tier_slug). It provides partial semantic grounding for the most important ones but leaves many undocumented.

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 the official mcp.ai marketplace and explains its core purpose of discovering, describing, and invoking MCPs. It distinguishes itself from siblings like authenticate or connect by explicitly stating it covers capability requests and the full search→describe→invoke flow, making its function unmistakable.

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: it specifies when to use invoke (single/occasional use) vs install (permanent toolkit addition), explains the conditions for connect/checkout links and when to retry, and mentions list_tools for currently callable tools. It also differentiates the prompt library actions from MCP actions, giving clear decision-making criteria.

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, idempotent, and non-destructive nature. The description adds useful behavioral details: it is hosted by the platform, requires pre-paid credit per query, no confidential data, and notes LGPD responsibilities for the customer. These go beyond the annotations and inform the agent about cost and legal usage, though it doesn't mention response format or errors.

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 relatively concise, opening with the core purpose in the first sentence, then adding hosting, payment, and legal context. It is structured and not overly verbose, though the LGPD and payment details could be streamlined. Still, each sentence adds value, so it earns a high score.

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?

With 5 parameters, no output schema, and no parameter descriptions, the description is incomplete. It does not indicate what the tool returns (e.g., installment details) or explain the pre-paid credit process beyond a mention. The lack of output expectations and parameter hints makes the tool under-specified for an agent to use 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?

Schema description coverage is 0%, so the description must compensate for the 5 parameters, but it provides no parameter-specific guidance. It only gives general domain context (IPTU) without explaining which parameters are required or how they relate to the query. This is a significant gap given the schema has no descriptions, leaving the agent without clarity on what values to supply.

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 consulting IPTU installments from Campinas city hall, using 'Prefeitura SP Campinas: Parcelas IPTU, consulta em fonte oficial' which specifies the verb (consulta) and resource (IPTU parcelas). It also distinguishes from sibling tools (which are generic platform tools) by focusing on a specific official data 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 provides clear context that this is for official Brazilian data (particularly IPTU) and mentions payment per query and no platform credentials needed. It implies usage for IPTU lookups but does not explicitly exclude alternative tools; however, siblings are unrelated, so no alternative is needed. It lacks explicit 'when not to use' but has enough context for the intended use case.

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 readOnlyHint=false and destructiveHint=false, so the description does not need to restate those. It adds the instruction to include the conversation for reproduction, which is useful context. However, it does not disclose any other behavioral traits (e.g., that a report is sent) beyond what is obvious. The idempotentHint=true in annotations is questionable, but the description does not contradict it.

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 concise sentences, front-loaded with the purpose and a clear instruction. There is no redundancy or unnecessary 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?

The tool has three parameters and no output schema. The description only hints at the conversation parameter, leaving message and context unexplained. It also does not describe the expected outcome or behavior. This is incomplete for a tool with minimal structured information.

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 schema description coverage at 0%, the description must compensate by explaining each parameter. It only mentions the conversation array for reproduction, but does not clarify what 'message' or 'context' mean. The required message field is left unexplained, making parameter semantics insufficient.

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 reports bugs, missing features, or feedback, using a specific verb and resource. It also instructs to include the conversation array for reproduction, adding context. Sibling tools are unrelated, so there is no ambiguity.

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 a usage instruction to include the conversation array, which helps the agent know what to pass. It implies use when encountering a bug or having feedback, but does not explicitly exclaim when not to use. Since siblings are unrelated, this is adequate.

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 safety. The description adds context by specifying it reports both MCP platform and adapter versions, which is useful for agents expecting the output structure. 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 sentence, clear and to the point, with zero filler. It is appropriately sized for a tool with no parameters.

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 is simple, has no parameters, and no output schema, the description is complete. It covers the purpose and what versions are shown, which is sufficient for an agent to invoke it.

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 parametersainer, so the schema is minimal. The description effectively states all there is to know (there are no inputs), making it unnecessary to describe parameters. A baseline of 4 is given for 0-param 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?

The description clearly states the tool shows the current MCP platform and adapter versions, with a specific verb and resource. It is distinct from siblings like authenticate or toolkit_info, though it might overlap somewhat with toolkit_info, but the version focus is clear.

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 versions but does not explicitly state when to use it versus alternatives like toolkit_infoahan or when not to use it. There is no mention of prerequisites or a scenario where it is preferred over other tools.

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, destructiveHint=false, and idempotentHint=true, covering safety semantics. The description adds valuable context beyond annotations by detailing the exact informational payload (installed MCPs, connection status, accounts, catalog counts), which helps agents understand what to expect without needing to guess output structure.

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 of 21 words, starting with the active verb 'Returns' and front-loading the key information. Every clause adds specific detail (MCPs, connection status, accounts, catalog counts) without redundancy, achieving high information density in minimal space.

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 low complexity (no parameters, no output schema), the description comprehensively covers the return semantics by listing all major content categories. It completely addresses what the tool does and what an agent can expect, making it appropriate for a read-only status query. No further detail is necessary for effective usage.

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 accepts zero parameters, so the rubric's baseline of 4 applies. There is no parameter schema to elaborate on, and the description does not need to address parameters. The schema description coverage is trivially 100% since there are no 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 a specific verb 'Returns' and clearly specifies the resource: the current toolkit state including installed MCPs, connection status, connected accounts, and catalog tool counts. This precisely defines the tool's purpose and naturally distinguishes it from sibling read-only tools like 'show_version' by the nature and detail of the returned data.

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 this tool (whenever toolkit state information is needed) by enumerating the exact data returned. However, it does not explicitly mention alternatives or scenarios where this tool should not be used, such as 'use show_version for version information only.' The context is clear and exclusion is implied but not stated.

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