Prefeitura SP Mogi das Cruzes: CPOM

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

Annotations indicate idempotent and non-destructive behavior. The description adds context about the two modes (session vs permanent) and explains how the token is used. It does not contradict annotations and provides supplementary behavioral details beyond what annotations state, though it doesn't describe consequences of invalid tokens or detailed state changes.

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 moderately long but highly informative, packed with specific instructions and structured into 'Best' and 'Or' alternatives. It front-loads the main purpose and provides actionable steps without wasteful filler, earning a score above average, though slightly verbose.

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 description covers the complete authentication flow: how to get the link, how to use a token for session login, and how to set up a permanent header. It does not mention the return value (e.g., the link itself), but since there is no output schema, it's not strictly required. The guidance is sufficient for an agent to know exactly how to invoke this 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?

The schema only defines a single 'token' string without detailed description (0% coverage). The description clarifies that 'token' is a JWT from the browser login, used in the call with '{ token: "<jwt>" }', adding meaning beyond the bare schema. It does not elaborate on format constraints or validation, but the basic semantics are well explained.

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's purpose: handling authentication for MCP.AI by logging in via browser, obtaining a token, and supporting both permanent and session-based setup. It specifies the resource (authentication) and differentiates from unrelated sibling tools by focusing solely on the auth workflow.

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 on when and how to use the tool: call with no arguments to get the login link, call with a token for session login, and recommends the permanent header configuration as the best practice. This clearly states usage scenarios and alternatives, though it doesn't mention when not to use it relative to siblings, the scope is 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 declare readOnlyHint=true and idempotentHint=true, indicating this is a safe read operation. The description adds context about return states (authenticated:true, pending[], connect_url) but does not mention lacks of behavior like rate limits or auth requirements. With annotations covering the safety profile, the description adds some value but is not rich.

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 every sentence adds value. It is succinct yet informative, covering both successful and failure states without extraneous 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?

Given the tool is simple (no params, no output schema), the description is complete enough for understanding what it returns. It could maybe mention the return format (e.g., JSON structure) but the context signals indicate that's covered elsewhere. For a status-check tool, this is adequate.

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 carries no parameter burden. The baseline for 0 params is 4, and the description does not need to explain parameters. It actually provides semantic meaning about the return content, which is helpful.

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 returns connection status and URLs, specifying what happens in different states (all providers connected vs credentials missing). It distinguishes from siblings like authenticate and show_version by focusing on status/URLs rather than performing authentication or showing version info.

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 (checking connection status) but does not explicitly state when to use it vs alternatives like authenticate or toolkit_info. It provides no exclusions or alternative guidance, but since it's a status-check tool, the usage context is fairly 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?

Discloses side effects beyond annotations: invoke runs one-off 'without adding the MCP to the toolkit and without bloating the tool list,' writes require 'workspace owner/admin,' paid tools return a checkout/top-up link, and credential needs return a connect link. No contradiction with readOnlyHint=false.

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?

Long but earned for a 14-action router; it is front-loaded with the core definition and progresses logically to permissions, billing, and prompt library. Slight redundancy around 'without adding... toolkit' and 'without bloating the tool list' keeps it from a 5.

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?

Very complete for the tool's complexity: it covers core flow, one-off invocation, install vs invoke, billing, auth permissions, result flags, and the prompt library. But with no output schema and a few unexplained enum actions like resume, it stops short of full completeness.

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 coverage, the description explains action-level semantics and concepts like tool_id and prompt variables, but 23 parameters remain largely map-by-name. It never addresses immediate, tier_slug, conversation, prompt_targets, or cancel_reason, so it only partially compensates for the missing schema descriptions.

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?

States that this is 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It clearly names the core search→describe→invoke flow and catalogs its own actions (install/uninstall/subscribe/cancel), distinguishing its 'report_bug sends feedback' action from the standalone sibling.

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?

Gives explicit when-to-use vs alternatives: 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use,' 'list_tools lists what is callable right now,' and 'request_mcp asks us to build a NEW MCP when nothing fits.' This is strong decision 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds meaningful context: it is the same public data available to citizens, not confidential, paid via prepaid credit, and subject to LGPD controller responsibility. This goes beyond the 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?

The description is four sentences and each sentence adds distinct information: source, hosting/payment, data nature, and LGPD responsibility. It is somewhat dense but not verbose, and no sentence is wasted.

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 one-parameter read-only lookup, the description covers source, cost, and legal/privacy context. However, it leaves the CPOM acronym undefined, gives no explanation of the response/return value, and omits CNPJ formatting details, which is a noticeable gap given there is no 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%, and the description does not mention the 'cnpj' parameter at all. The parameter name is self-explanatory, but no added meaning is provided regarding expected format, punctuation, length, or validation, so the description fails to compensate for the schema 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 identifies the action as a 'consulta' (query) of CPOM from an official source for Prefeitura SP Mogi das Cruzes, which distinguishes it from the unrelated sibling platform tools. However, it never explains what CPOM is or what the query returns, so it is clear but not fully specific.

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: hosted by the platform, no platform credentials required, prepaid credit per consultation, and official public data source. It does not explicitly name alternatives or when-not-to-use, but the sibling tools are all generic platform utilities, so this is acceptable context without 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 convey idempotency, non-readonly, and non-destructive behavior. The description adds the useful detail that the conversation is needed for reproduction, but it does not disclose side effects such as whether a ticket is created or data is sent externally. This is adequate but not rich.

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 with no filler. It front-loads the action and then provides the most important invocation 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 is simple with three parameters and no output schema, so the description gives a workable overview. However, the conversation string/array mismatch and lack of explanation for message and context mean the agent must infer some semantics from parameter names and defaults.

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 parameter meaning. It explains the conversation parameter's purpose but calls it an 'array' while the schema types it as a string, which is misleading. It also does not clarify the required 'message' parameter or the optional 'context' parameter beyond their names.

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 a bug, missing feature, or feedback, using a specific verb and resource. It is easily distinguished from sibling tools like show_version and authenticate, 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?

It gives explicit invocation guidance by instructing the agent to include the conversation with recent messages for reproduction. It does not explicitly state when not to use it, but no alternative feedback tool appears among siblings, so the context is sufficient.

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, which cover safety expectations. The description adds no extra behavioral context (e.g., return format or side-effect nature) beyond what annotations provide, but it remains consistent and non-contradictory.

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, front-loaded sentence with no wasted words. It efficiently communicates the tool's function.

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 tool with no parameters and no output schema, the description is fully adequate. It clearly states the tool's purpose and behavior, leaving no significant gaps.

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%, so the description needs no parameter clarification. According to the guidelines, a baseline of 4 applies for zero-parameter 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 uses a specific verb 'Show' and a clear resource 'current MCP platform and adapter versions', distinctly separating it from siblings like authenticate or connect. It is not a tautology and fully captures the tool's 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 the tool (when needing version information) but does not explicitly state usage context or alternatives. It lacks guidance on when not to use or how it relates to sibling 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, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe, idempotent read operation. The description adds a bit of context about what the state includes (installed MCPs, connection status, accounts, catalog tools) but doesn't disclose any additional behavioral traits like potential latency or data freshness. Since descriptions don't need to repeat annotations and the added context is modest, a 3 is appropriate.

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, front-loaded sentence that lists the key components of the toolkit state. It is concise, directly states the purpose, and includes no fluff. Every element in the sentence adds information about the tool's output, making it highly efficient.

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 that the tool has no parameters and no output schema, the description needs to convey what the tool returns, which it does by enumerating the elements of the toolkit state. It is reasonably complete for a read-only informational tool with zero complexity. However, it could mention how to interpret the connection statuses or provide a hint about the structure of the return value, but this is 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 the schema description coverage is 100% (vacuous). The description doesn't need to explain parameter semantics because there are none. With no parameters, the baseline is 4, and the description adds value by explaining what the output contains, which compensates for the absence of an output schema.

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 what the tool does: returns the current toolkit state including installed MCPs, connection status, associated accounts, and catalog tool counts. It distinguishes itself from siblings like 'authenticate', 'connect', or 'show_version' by focusing on aggregate state information. However, it could be more specific about the exact resource (toolkit state) and the verb 'returns' 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 the tool is used to retrieve an overview of the toolkit state, but it doesn't explicitly state when to use it versus alternatives like 'show_version' or 'connect'. It doesn't provide usage exclusions or alternative tool references. There is no guidance on prerequisites or context, though the zero-parameter nature makes it straightforward.

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