Prefeitura CE Fortaleza: CPOM

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

The description goes beyond the annotations by explaining the two modes (permanent config header vs session-only pasted token) and the no-args behavior of returning a login link. It doesn't cover error/return behavior for invalid tokens, but annotations already provide idempotent/safe hints.

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, front-loads the purpose, and every clause adds actionable setup information without repetition or filler.

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 one-parameter authentication tool with no output schema, this is reasonably complete: it covers setup modes, argument semantics, and no-args behavior. It could mention success/failure responses or security implications, but those are not essential for invoking 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 schema only defines token as a string; the description adds meaning by specifying it should be a JWT copied from the browser, and by clarifying that omitting it returns the link. With 0% schema description coverage, this compensation is useful, though format details are still light.

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 authentication for MCP.AI in IDE agents, using specific verbs like 'log in', 'copy the access token', and 'call with token'. It does not explicitly differentiate from sibling tools such as '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?

It gives concrete guidance: use no-args to obtain a link, pass a token for session-only login, and prefer adding a header to the server config for a permanent non-expiring connection. It doesn't mention alternative sibling tools or when-not-to-use, so not a 5.

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 false. The description adds valuable behavioral detail, specifying return fields like authenticated, pending[], and connect_url under different conditions, going beyond the annotation basics.

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 followed by conditional behavior. Every word 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?

The tool is simple with no parameters and no output schema. The description covers the main states (all connected vs missing credentials) but does not mention partial-connection scenarios, leaving a small gap for 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?

The tool has zero parameters and schema coverage is 100%. Baseline for zero parameters is 4, and the description appropriately adds no parameter information since none exist.

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 it returns connection status and URLs, using the specific verb 'returns' and a defined resource. It distinguishes itself from the sibling 'authenticate' tool by focusing on status rather than 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 clear context for when to use the tool: to check connection status. It explains behavior for both connected and missing-credential cases, though it does not explicitly name alternative tools or state when not to use it.

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 are thin (readOnlyHint=false, idempotentHint=false), so the description carries a heavy burden and delivers richly. It discloses that invoke runs one-off WITHOUT adding the MCP to the toolkit or bloating the tool list, that writes require workspace owner/admin, that search/describe flag installed_in_toolkit vs installed_in_workspace, and what connect/checkout links do. No contradiction with annotations — readOnlyHint=false aligns with the described writes. Exceptional behavioral disclosure.

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?

Every sentence earns its place — there is zero fluff and the information density is high. But it is delivered as one giant run-on paragraph with no bullets, breaks, or sectioning, which makes a 14-action, two-domain (MCP + prompt library) tool very hard to scan. Dense but poorly 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?

For an exceptionally complex tool (14 actions, 23 params, no output schema), the description covers operational completeness well: the full search→describe→invoke pipeline, install-vs-invoke semantics, credential and payment flowbacks, auth requirements for writes, and the prompt-library sub-flow. It even discloses several return behaviors (connect link, checkout link, shareable mcp.ai/p/<slug> link). Gaps remain in parameter semantics and certain return formats, but given no output schema, this is strong.

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% across 23 parameters, so the description must compensate entirely. It does explain the action enum thoroughly (all values with their intents) and touches on key params (mcp_id, tool_id, arguments, tier_slug). However, a large portion of params — conversation, prompt_tool, prompt_vars, prompt_targets, cancel_reason, cancel_comment, report_context, request_details, immediate, limit, message, prompt_body, prompt_slug, request_name — are never mentioned. Partial compensation only for a 23-param 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 description opens with a specific, concrete purpose: 'the in-platform catalog of every MCP/tool, AND the way to run them.' It enumerates all 14 action values with their functions (search/describe/invoke flow, install vs invoke, prompt-library operations) and clearly differentiates this meta-tool from its siblings — authenticates, connects, and singular query tools are not catalog gateways. The verb-resource scope is 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?

Outstanding when-vs-alternative guidance. It explicitly distinguishes invoke ('prefer invoke for a single/occasional use') from install ('Use install only to make an MCP PERMANENT'), explains when search/describe are the entry path, and covers conditional flows (credential → connect link, empty wallet → checkout link, then retry). It even ties to siblings implicitly by noting report_bug is an action here. This is model for 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 and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: queries are paid via prepaid credit, no platform credentials are required, the data is the same available to citizens and not confidential, and the client is the data controller under LGPD. No contradiction with annotations was found.

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 three sentences and front-loaded with the core purpose in the first sentence. The additional operational and LGPD context is concise and adds relevant information without excessive verbosity.

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 tool, the description covers the main purpose, payment model, and data-control responsibilities. However, it leaves gaps: 'CPOM' is undefined, the CNPJ parameter is not explicitly tied to the query, and there is no mention of expected return/result behavior despite there being 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 never mentions the 'cnpj' parameter, its format, or its role in the query. The parameter name alone is somewhat self-explanatory in a Brazilian context, but the description does not compensate for the missing schema guidance.

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 states a read/query operation ('consulta em fonte oficial') targeting CPOM data from Prefeitura CE Fortaleza, which is specific enough to distinguish it from the unrelated sibling tools. However, it never explains what 'CPOM' stands for and broadens to generic 'fontes e órgãos oficiais brasileiros', which slightly dilutes the specificity.

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 operational context (hosted by the platform, no platform credentials, pay-per-query with prepaid credit) but no guidance on when to use this tool versus alternatives. There is no explicit when-to-use or when-not-to-use statement, and no alternatives are mentioned.

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 indicate this is not read-only (readOnlyHint: false) but also not destructive (destructiveHint: false), which is consistent with 'report' implying a side-effectful action. The description adds context about including conversation data for reproduction, going slightly beyond annotations. However, it does not discuss idempotency despite idempotentHint: true being set, missing an opportunity to clarify behavior. 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?

Two sentences: the first states purpose, the second gives a concrete instruction. Every word earns its place, and the most important information is front-loaded. No fluff.

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 only 3 parameters and no nested objects, the description is under-specified. It omits the purpose of the required 'message' parameter and the 'context' field, and provides no output schema or return expectations. For a bug-reporting tool, it leaves the agent guessing about what to send and what to expect in response.

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 explain parameters. It only mentions 'conversation array' indirectly, but fails to explain 'message' (required) or 'context.' This leaves the agent without crucial parameter meaning, making the tool difficult to invoke correctly.

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: 'Report a bug, missing feature, or send feedback.' This uses a specific verb ('report'/'send') and identifies the resource (bug/feedback). It differentiates itself from sibling tools like 'authenticate' and 'connect' 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 mentions including the conversation array 'for reproduction,' which implies when to use it (when a bug needs debugging). However, it does not explicitly state when to prefer this over alternatives or provide any exclusion criteria. The guidance is implied but not explicit.

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 established. The description adds scope definition ('platform and adapter versions') which complements, rather than contradicts, the annotations. 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?

A single, complete sentence with zero wasted words. 'Show' is front-loaded, and every remaining word ('current', 'MCP platform', 'adapter versions') carries meaning. Perfectly proportionate to the tool's simplicity.

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 version-inspection tool with zero parameters, rich safety annotations, and no output schema, the description covers all essential behavioral context. Slight deduction only because return-value format isn't hinted, but that's not required in the absence of an 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?

With zero parameters, the baseline of 4 applies as the description appropriately says nothing about parameters. Schema coverage is trivially 100% with an empty properties object, so there's no gap for the description to fill.

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 clear, active verb ('Show') with a specific resource ('MCP platform and adapter versions') and temporal scope ('current'). It's immediately distinguishable from siblings like 'toolkit_info' by making its exact function self-evident.

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 context for when to use it (whenever version info is needed) and the word 'current' implies it's not a history command. However, it doesn't explicitly discuss alternatives or exclusions, though the trivial nature of a version check makes this less critical.

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 safety is covered. The description adds meaningful context beyond annotations by specifying exactly what state information is returned, including per-MCP connection status and account details. It does not mention response shape or freshness, 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?

The description is a single, well-structured sentence that front-loads the main purpose ('Returns the current toolkit state') and then enumerates the returned details compactly. Every clause provides useful information, with no redundancy or filler.

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 parameterless read-only status tool with no output schema, the description is complete: it names all major output components (installed MCPs, connection status, accounts, catalog tool counts). The absence of an output schema is adequately compensated by this explicit enumeration. The tool's simplicity means no further behavioral or format details are 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 zero parameters, and the schema is trivially 100% covered by the empty properties object. The description correctly focuses on the return value rather than parameters, and no parameter semantics are missing. Baseline 4 applies for parameterless 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 begins with the specific verb 'Returns' and the resource 'current toolkit state', then details exactly what that state includes: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like authenticate, connect, and show_version.

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 context that this tool is for inspecting toolkit state, including MCP installation, connection status, and account linkage. It does not explicitly name alternatives or exclusion criteria, but the detailed output list makes the intended usage evident compared to action-oriented siblings.

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