SEFAZ DF: IPTU (Emissão Guia)

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

Annotations indicate readOnlyHint=false and idempotentHint=true, and the description appropriately discloses the mutation by describing config modification and session-only storage. It explains the browser login flow and token handling, adding context not in annotations. Minor gap: it doesn't explicitly state whether the server state is altered beyond the config header, but overall it 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?

The description is efficient and logically structured. It leads with the core action, then presents the preferred method, followed by the alternative. Each sentence contributes value, though slightly verbose in explaining both flows; still, it remains concise enough.

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 single parameter, no output schema, and provided annotations, the description is complete. It covers both usage modes, the token's purpose, and the expected outcome (link vs session). No essential information is missing for correct tool 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?

Despite 0% schema description coverage, the description fully explains the only parameter 'token': it is a JWT used for session-only login, and that omitting it returns a login link. This adds substantial meaning beyond the bare schema, fully compensating for the lack of schema documentation.

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 with MCP.AI by logging in and providing an access token. It specifies two distinct methods (permanent config header or session-only token) and differentiates from siblings like 'connect' by focusing on token acquisition and usage.

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 guidance: 'Best: add it to this server's config as a header' recommends the permanent method, while 'or use paste it here for a session-only login' explains the alternative. It also states when to call with a token ('after the user pastes') and when to call without ('to get the link'). These clear directives eliminate ambiguity.

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 safety profile is known. The description adds valuable behavioral detail by disclosing the exact response fields (authenticated, pending[], connect_url) and how they vary based on connection status, which goes beyond annotation information.

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 function, and every word earns its place. It efficiently conveys conditional behavior without 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?

While the description explains two clear states (all connected, missing credentials), it omits partial connectivity scenarios (some providers connected, others not). Given no output schema, the description should more fully cover possible return states for a status 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?

With zero parameters, the baseline is 4. The description correctly focuses on the tool's behavior rather than parameter details. No parameter information 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?

The description clearly states the tool's function: returning connection status and URLs. It specifies the verb 'Returns' and the resource 'connection status and URLs', and it distinguishes itself from sibling tools like 'authenticate' by focusing on status rather than the authentication action.

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 context on when the tool behaves differently (all providers connected vs. missing credentials) but does not explicitly state when to use this tool over alternatives like 'authenticate'. It implies usage for checking status before authenticating but lacks explicit exclusions or alternative references.

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?

Beyond the sparse annotations (readOnlyHint: false, destructiveHint: false, idempotentHint: false), the description richly discloses behavior: invoke 'runs the tool pontualmente (one-off), without adding the MCP to the toolkit', returns connect links for auth and checkout links for empty wallets (with a retry instruction), flags installed_in_toolkit vs installed_in_workspace, and declares that writes require workspace owner/admin. This adds substantial context that annotations alone cannot convey. 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 information-dense and front-loaded with the core definition, but it is a single unbroken wall of prose with no bullets, headers, or flow breakdown. Every sentence earns its place in terms of content, but the structure makes it hard to scan for an agent deciding which sub-action to invoke — better formatting (e.g., separating the core flow, invoke/install tradeoff, permission rules, and prompt library) would improve parseability without adding length.

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 tool with no output schema and thin annotations, the description covers the main flows comprehensively: the search→describe→invoke pipeline, auth/payment edge cases, install-vs-invoke decision, permission requirements, and the prompt library. Gaps remain in return-value expectations per action (what search/describe/list_tools return beyond flags) and edge cases for subscribe/resume/cancel. It compensates well for the missing output schema but is not exhaustive across all sub-actions.

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 carries a heavy burden. It explains the action enum thoroughly (each value maps to a flow described in prose), and conceptually touches on tool_id, arguments, and prompt fields (prompt_vars as {{variables}}, publish_prompt returning a shareable link). However, it does not explain the semantics of many parameters — conversation, immediate, tier_slug, cancel_reason/comment, prompt_targets, report_context, prompt_category, prompt_description, request_details — leaving the agent to guess their structure and intent.

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 of what the tool is: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It then enumerates capability requests it covers ('find an MCP that does X', 'consulta um CPF') and distinguishes its sub-actions (search/describe/invoke/install) with distinct roles, clearly setting it apart from the sibling tools.

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 when-to-use guidance: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT', plus when to touch the prompt library vs MCP actions. It explicitly contrasts invoke (one-off, no toolkit bloat) with install (permanent), and names the alternatives (list_tools, subscribe/cancel, report_bug, request_mcp) — though these are sub-actions rather than sibling tools, the guidance is unambiguous and actionable.

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=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the insight that the conversation array is meant for reproduction, which is useful context, but does not go beyond that. There is 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 two short sentences, front-loaded with the purpose. Every word earns its place, and it avoids unnecessary fluff or repetition of schema fields.

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 3 parameters and no output schema, the description covers the core purpose and a key usage requirement, but it does not sufficiently explain all parameters (especially 'context') or clarify the serialized format of 'conversation'. This leaves the agent with a moderate risk of misusing the 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?

Schema description coverage is 0%, so the description must compensate. It explicitly mentions the conversation array and implies the need for a message, but it does not clarify the 'context' parameter or explain that 'conversation' is a JSON-encoded string (the schema shows it as a string). The description is incomplete for agents relying on it to understand all 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 clearly states the tool's purpose with specific verbs and resources: 'Report a bug, missing feature, or send feedback.' This distinguishes it from sibling tools like 'authenticate', 'marketplace', and 'sefaz_df_iptu_consultar', which serve entirely different functions.

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 for usage by instructing the agent to include the conversation array with recent messages for reproduction. It does not explicitly list exclusions or alternative tools, but the purpose is specific enough that an agent would naturally use this tool for reporting issues rather than for other operations.

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 adds context beyond annotations: it mentions prepaid credit (payment requirement) and that no platform credentials are needed, which are useful operational details. However, it does not disclose other behavioral aspects like rate limits, error handling, or data refresh cadence. It aligns with readOnlyHint and idempotentHint, so no contradiction, but the added value is moderate.

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 paragraph of four sentences, but includes redundancy (e.g., 'consulta em fonte oficial' and 'Consulta informação de fontes e órgãos oficiais' repeat the official-source theme) and legal boilerplate (LGPD) that could be trimmed. It is not overly long, but not tightly structured; the essential information could be conveyed in fewer sentences.

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 two parameters and no output schema, the description lacks parameter documentation and return-value expectations. It provides background on official data and payment, but does not explain how to input the property registration number or what the query result looks like. This leaves the agent under-informed for correct invocation and result 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 schema description coverage is 0%, so the description must compensate by explaining parameters, but it does not. Neither 'inscricao_imovel' nor 'exercicio' are described. The only hint is 'consulta' implying a lookup, but no parameter meaning, format, or constraints are provided. This is a significant 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 states the tool queries IPTU data from official SEFAZ DF sources, using the verb 'consulta' and specifying the resource. It distinguishes from generic platform siblings like authenticate or report_bug, which are unrelated. The phrase 'Emissão Guia' adds a potential action, but the primary purpose is a query, so it's clear enough though slightly ambiguous.

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, nor does it mention exclusions or conditions. It implies usage for IPTU queries but lacks any 'when to use' or 'when not to use' statements. The siblings are unrelated, so differentiation is not critical, but the absence of any usage context leaves the agent without decision support.

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, non-destructive, and idempotent behavior. The description adds no additional behavioral details. Since annotations cover safety, the description meets the baseline transparency requirement.

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?

Single, direct sentence without any redundant wording. Efficiently conveys the tool's action and target.

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 informational getter with no parameters and no output schema, the description fully covers what the tool does. No additional context is necessary.

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, so there is nothing to explain. The baseline for zero parameters is 4, and the description correctly omits any parameter-related information.

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 specific action (show) and resource (current MCP platform and adapter versions). It distinguishes this tool from siblings like authenticate or connect, which serve different 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 tool's purpose is self-evident, making its usage context clear. It doesn't explicitly mention alternatives, but given the simplicity, the context is sufficiently implied. Minor deduction for not explicitly contrasting with 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, idempotentHint, and destructiveHint. The description adds valuable context by specifying what the returned state includes (installed MCPs, status, accounts, catalog counts), which goes beyond the annotation safety profile. It doesn't mention any edge behaviors, but for a read-only info tool this is sufficient.

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?

A single, well-structured sentence that front-loads the verb and resource, then specifies the four return categories. Every part adds value; 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?

The tool is simple (no parameters, no output schema), and the description fully covers what the agent needs to understand what it returns. The sibling tools are clearly action-oriented, and the description makes it obvious this is a read-only status check.

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 zero parameters, the description doesn't need to explain parameter semantics. The baseline of 4 applies due to no parameters, and the description's focus on return content is appropriate.

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 with a specific verb ('Returns') and detailed resource ('current toolkit state'), enumerating exactly what it provides: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling action-oriented tools like authenticate and 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 implies usage for when you need an overview of the toolkit's current state, but it doesn't explicitly state when to use it over alternatives or when not to use it. Siblings like authenticate and connect are clearly different actions, but there's no direct comparative guidance.

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