Polícia Federal: Situação e Regularidade de Empresa de Segurança Privada

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

Goes beyond annotations by explaining two usage modes (permanent vs. session) and that calling with no arguments returns a link. It does not contradict the annotations (idempotent, non-destructive) and adds practical behavioral context.

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 but somewhat dense, packing multiple instructions into a single sentence with multiple clauses. It is understandable but could be broken into clearer steps. Still, it avoids unnecessary 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?

The description mentions that calling with no args returns a link, but does not specify what happens when a token is passed (e.g., success message or error handling). Given the lack of an output schema, this omission leaves some ambiguity about the tool's return value.

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 description clarifies that the 'token' parameter is a JWT obtained from the browser, and that it is optional (since no args returns the link). This fully explains the meaning and purpose of the parameter.

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 explicitly states the tool is for authentication, clearly distinguishing it from sibling tools like connect or show_version. It names the resource (MCP.AI) and the verb 'authenticate' implicitly through context.

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 step-by-step guidance: login via browser, copy token, then either add to config for permanent access or pass as a parameter for session-only. Also explains the no-args invocation to get the login link. Clearly instructs when and how 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing exact state-dependent outputs: 'authenticated:true and empty pending[]' versus 'connect_url for the toolkit and per-install URLs.' This goes beyond the annotations and clarifies what the response looks like in different scenarios.

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 only two sentences and front-loads the core purpose in the first sentence. The second sentence adds conditional detail without fluff or redundancy. Every sentence earns its place.

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, read-only, zero-parameter status tool, the description covers the two most important response states and references 'pending[]' to imply partial connection scenarios. It is mostly complete, though it could more explicitly describe intermediate states where some providers are connected and some are pending, and what the returned URLs are used for.

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, so there are no parameter semantics to explain. Schema description coverage is 100% vacuously, and with 0 params the baseline is 4. The description correctly avoids inventing parameter details that do not 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 opens with a specific verb and resource: 'Returns connection status and URLs.' It clearly states what the tool produces and its scope (connection status/URLs). This distinguishes it from the sibling 'authenticate' tool, which is presumably about initiating authentication rather than reporting on it.

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 explains conditional output (authenticated:true vs connect_url), which implies the tool is for checking connection state. However, it does not explicitly say when to use this tool over alternatives like 'authenticate' or when not to use it, leaving usage guidance implicit rather than 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?

Without relying on annotations, the description expldoes the key behavioral nuance that invoke works even when the MCP is NOT installed and runs one-off 'sem ranhura' without bloating the tool list. It discloses auth requirements (workspace owner/admin writes), the connect-link and checkout-link payment/credential flow, and the subtle two meanings of installed_in_toolkit vs installed_in_workspace. Annotation openWorldHint=true is consistent with the description's key distinction of the marketplace being broader than the installed toolkit. The word 'pontualmente' (a Portuguese-language annotation in the original text) reads as a one-time/contingent run but does not contradict.

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 packs an enormous amount of information into a single dense paragraph with clear sequencing (core flow → key behavior → install vs invoke → auth → prompt library) and good signal words like 'KEY:', 'Use install only to...'. It loses a point for length and run-on feel; a few sentence breaks or bullets would improve scannability, but every sentence carries unique, fight-for-its-place meaning.

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?

This is an exceptionally complete description for a tool with 23 parameters, no output schema, and a complex state machine (actions, auth, billing, prompts). It covers the finite-state machine of the action enum, side effects, error/link flows (connect, checkout), permissions, and even the semantic difference between searchable catalog and callable tools. The description fully enables an agent to sequence calls correctly, including the retry-after-payment step.

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 description does some hard lifting by explaining that 'action' (search/describe/etc.) is the dispatcher and that some params like mcp_id and tool_id pair with actions, plus giving domain knowledge about prompt_vars/publish flow. However, with 23 parameters and 0% schema coverage, the description cannot plausibly document each one—it groups them by phase (search_prompts, get_prompt, publish_prompt) and explains the two-level granularity of mcp_id vs tool_id. Still, it leaves the meaning of params like promotion naming to the user, which is accepted for a description of this breadth.

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 defines the marketplace tool as both a catalog and execution runtime for MCPs, explicitly listing 14 distinct actions from search to publish_prompt. It strongly differentiates from siblings by naming the official mcp.ai marketplace and explaining the core flow (search → describe → invoke) and the key distinction between invoke and install. The description even includes real user examples like "consulta um CPF" which grounds its purpose concretely.

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 explicitly states when to use invoke vs install ('Use install only to make an MCP PERMANENT in the active toolkit...prefer invoke for a single/occasional use') and names alternatives like list_tools for current callables. It gives concrete decision rules: 'Search/describe flag installed_in_toolkit vs installed_in_workspace' and explains what happens when credentials are needed (returns connect link) or wallet is empty (checkout link), including the retry instruction. This is textbook usage 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, idempotentHint, and destructiveHint false, and the description adds meaningful behavioral context: the query is hosted by the platform, requires no platform credentials, incurs prepaid per-query costs, and returns the same public information available to citizens. It also clarifies data controller responsibilities under LGPD, which goes 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 three sentences and reasonably dense, with the core purpose in the first sentence. The LGPD and payment details add useful context rather than filler, although some legal phrasing could be trimmed without losing critical information.

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 five parameters, no output schema, and 0% schema description coverage, the description covers source, pricing, and data governance but omits expected return values/result format and guidance on the optional credential parameters. It is adequate for a simple public-data query but incomplete for full invocation confidence.

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 needed to explain the parameters. It does not clarify the CNPJ format or the purpose of optional fields like login_cpf, login_senha, pkcs12_cert, and pkcs12_pass. The note about 'no platform credentials' is useful but does not compensate for the undocumented credential-related 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 states a specific action and resource: consulting the situation/regularity of a private security company via the Federal Police official source. The tool name 'pf_regularidade_empresa_consultar' and the opening sentence align, and it is clearly distinguishable from the generic sibling tools (authenticate, connect, marketplace, etc.).

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 context—official Brazilian source, paid per query with prepaid credit, no platform credentials, and non-confidential data—but it does not explicitly say when to choose this tool over alternatives or when not to use it. There are no exclusions or alternative tools referenced, so guidance is only implied.

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 state readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds 'Include the conversation array with recent messages for reproduction,' which hints at expected input format but does not disclose what happens after submission (e.g., confirmation, storage, asynchronous delivery). It provides some added context but not rich behavioral details; 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 a single, front-loaded sentence that states the purpose and gives a key usage hint. There is no fluff or redundant information. It is appropriately concise for a simple 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 3 params and no output schema, the description covers the main purpose and one usage detail but does not describe what the user can expect as output (e.g., success message, issue ID, next steps). It also leaves 'context' unexplained. While the tool is simple, the description is not fully complete for a first-time user.

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 mentions 'conversation array' (matching the 'conversation' parameter) but does not explain 'message' (the required field) or 'context'. The schema lacks descriptions, so the tool relies on the description, which is insufficient for two of the 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?

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It uses a specific verb (report/send) with a clear resource (bug/feature/feedback). No sibling tool has a similar function, making it distinct.

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 hint: 'Include the conversation array with recent messages for reproduction.' While it does not explicitly mention when not to use this tool, the sibling tools (authenticate, marketplace, etc.) are clearly different, so the context is sufficient. It could be more explicit about alternatives, but the guidance given is useful.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds that it covers both platform and adapter versions, which is useful context beyond 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?

Single, concise sentence that is front-loaded and directly states the tool's purpose. 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?

For a simple read-only tool with no parameters and no output schema, the description is sufficient. It clearly states what versions are shown, and the annotations cover safety.

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?

Tool has no parameters, so schema coverage is 100%. The description doesn't need to explain parameters; the baseline for zero params is 4.

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 show current MCP platform and adapter versions. The verb 'show' and resource 'versions' are specific, and it distinguishes from siblings like authenticate and connect, which handle different concerns.

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 implies usage when version info is needed, but no explicit when-to-use or alternatives are mentioned. Given the obvious purpose, this is adequate but lacks explicit 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?

The annotations already declare this as a read-only, idempotent, non-destructive operation. The description adds value by specifying exactly what state it returns (installed MCPs, connection status, accounts, catalog counts), which goes beyond the annotations. No contradictions. It doesn't mention performance or whether it may include cached data, but for a status 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 sentence that packs a lot of specific detail without any padding. It is concise, front-loaded with the main purpose, and immediately enumerates the key data points. Every element is informative and there is zero waste.

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 stateless status tool with zero parameters and clear annotations, the description is complete. It covers what is returned, the read-only nature is clear from annotations, and it is sufficiently differentiated from siblings. The description adds enough context to fully understand the tool's purpose and output.

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 takes zero parameters, and the schema coverage is 100%. The description adds meaning by explaining what the returned information contains, effectively describing the output. While it doesn't describe parameter semantics (there are none), it compensates by clarifying the return value, which is the main semantic value here.

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') with a clear resource ('current toolkit state') and enumerates exactly what is included (installed MCPs, connection status, accounts, catalog tool counts). It distinguishes itself from siblings like 'connect' and 'authenticate' by clearly being a read-only status tool, and it is broader than 'show_version', which likely shows just the 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 clearly implies the tool is for checking the current state of the toolkit without modifying anything. While it doesn't explicitly say 'use this instead of X', the read-only nature and listing of specific data make the use case evident. It could benefit from noting when not to use it (e.g., when you need to connect an account), but the intent is clear.

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