SEMA MT: APF Rural

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

Annotations indicate idempotentHint=true and destructiveHint=false, which the description does not contradict. The description adds behavioral context: calling with no args returns a link, while calling with a token performs session login. It also explains the token is a JWT and distinguishes permanent vs session connections. This goes beyond annotations by detailing the auth flow and token format.

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 block of text but is well-structured with clear alternatives (config vs session) and invocation modes. It includes necessary context for IDE agents without being overly verbose. Every sentence contributes to understanding the tool's usage, though it could be slightly tightened without losing value.

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 (one optional param, no output schema) and the description covers both permanent and session auth paths, including token format and link retrieval. It does not explicitly describe the return value, but the phrase 'get the link' implies it. Overall, it provides sufficient context for an agent to invoke the tool 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?

Although schema coverage is 0%, the description gives clear meaning to the single optional 'token' parameter: it is a JWT that can be pasted for session login. It also explains that omitting it triggers a link request. This fully compensates for the lack of schema docs and provides semantic value beyond the bare type definition.

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: authenticating the user by logging in via browser and obtaining an access token. It distinguishes itself from siblings by focusing on the authentication flow, and it specifies the resource (access token) and the action (log in). The verb 'authenticate' is specific and the description elaborates on the mechanism.

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 when-to-use instructions: either add the token to the server's config for permanent access, or paste it for session-only login. It also explains the two invocation modes (with token or no args). It clearly states how the tool fits into the authentication workflow, even if it doesn't explicitly exclude 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, destructiveHint=false, and idempotentHint=true. The description adds value by specifying the behavioral states: when all providers connected vs. missing credentials, and what fields (authenticated, pending, connect_url, per-install URLs) are returned in each case. This goes beyond the 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 concise sentences with front-loaded purpose. Every clause adds information about behavior, and there is 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?

With no parameters and no output schema, the description carries the burden of explaining return values. It covers both success and missing-credential cases, and mentions specific fields like 'authenticated', 'pending[]', and 'connect_url'. It could clarify what 'pending' represents, but overall it is complete for a simple read-only 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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter details but none are needed. It does not repeat schema information, and the schema is empty, so the description compensates adequately by explaining the response behavior.

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 verb and resource: 'Returns connection status and URLs.' It distinguishes from siblings like 'authenticate' (which likely initiates auth) and 'toolkit_info' by focusing on connection state, and it details the two possible outcomes, making the purpose 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 implies use for checking connection status, but does not explicitly state when to use it versus alternatives like 'authenticate' or 'toolkit_info'. There is no exclusions or alternative guidance, so it relies on the reader to infer the context.

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 only declare openWorldHint=true and readOnlyHint=false, leaving the burden on the description, which delivers: invoke runs tools even when not installed without bloating the toolkit, credentials yield a connect link, empty wallets yield a checkout link, writes require workspace owner/admin, and prompt links open without login. Nothing contradicts the annotations; the disclosure of state-changing behavior complements 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?

The text is long but dense — the flow arrows (search → describe → invoke), the "KEY:" marker, and the prompt-library paragraph each carry unique information that earns their place. It loses a point for being a near-wall-of-text where bullet-point structure or per-action formatting would improve scannability for such a multi-action 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 23-parameter, 14-action dispatcher with no output schema, the description covers the core execution flow, auth/paywall side effects, permissions, and the secondary prompt-library subsystem, which is strong. It omits details on return shapes, error behavior, the `resume` action, and the `immediate` parameter, so it's thorough but not exhaustive.

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 — and it thoroughly explains the central `action` dispatcher (all 14 enum values except `resume` are explicated) and key params like tool_id and prompt_slug. However, many params (limit, immediate, tier_slug, conversation, prompt_targets, report_context, request_details) receive no semantic explanation, so compensation is only partial.

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 definition — "the in-platform catalog of every MCP/tool, AND the way to run them" — and maps it to concrete capability requests like "find an MCP that does X" and "consulta um CPF". It clearly distinguishes the umbrella marketplace tool from siblings by naming the search→describe→invoke core flow and the separate prompt-library facet.

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?

Explicit when-to-use guidance is everywhere: "prefer invoke for a single/occasional use" vs "Use install only to make an MCP PERMANENT", and "request_mcp asks us to build a NEW MCP when nothing fits". It also differentiates invoke from list_tools (callable right now) and explains when connect/checkout links interrupt the flow.

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, destructiveHint=false, and idempotentHint=true, establishing the safety profile. The description adds the useful behavioral instruction to include the conversation array for reproduction. However, it does not disclose what happens after reporting (e.g., confirmation, transmission) beyond the 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 purpose and adding one practical instruction. Every word earns its place, with no redundancy or 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?

The tool is simple (3 string params, no output schema), and the description covers its core purpose and the non-obvious conversation parameter. Annotations handle safety. It lacks detail on parameter contents but is otherwise adequate for a reporting 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 0% schema description coverage, the description needed to compensate but only explains the 'conversation' parameter's purpose (for reproduction). It does not clarify the required 'message' parameter or the optional 'context' parameter. The purpose statement implicitly suggests content for message but leaves it to the agent.

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 reports a bug, missing feature, or feedback, which is a specific verb+resource. This clearly distinguishes it from sibling tools like authenticate, connect, and show_version, 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 description provides clear context for usage: to report bugs, missing features, or feedback. It also advises including the conversation array for reproduction, but it does not explicitly list exclusions or alternative tools. Given the sibling tools are thematically distinct, this 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=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable context: hosted on the platform, no platform credentials needed, paid per query with prepaid credit, returns official (non-confidential) data, and clarifies LGPD responsibilities. This goes beyond the 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 paragraph, reasonably concise, and front-loaded with the tool's purpose. However, it includes legal and payment details that, while useful, could be trimmed or positioned later. Still, every sentence adds relevant context.

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 moderate complexity (5 optional parameters), no output schema, and useful annotations, the description covers payment, data nature, and legal aspects but lacks param semantics and usage examples. The absence of output schema increases the need for description to explain return behavior, which is not addressed.

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 mentions no parameters. The schema lists five properties (apf, car, cpf_responsavel, cpf_proprietario, cnpj_proprietario) but without any explanation, leaving the agent to guess their meaning and optionality. The description should clarify that these are search filters or identifiers.

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 it is a 'consulta' (query) for 'APF Rural' from an official source, which indicates a read operation. However, it does not specify what 'APF' stands for or what the result contains, and it lacks differentiation from sibling tools (though siblings are unrelated system 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 explains the payment model (pre-paid credits) and the LGPD data controller responsibility, but it does not specify when to use this tool over others or provide exclusions. It implies a paid query but no clear guidance on appropriate use cases beyond the general 'consulta' context.

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, non-destructive behavior, and the description's 'Show' aligns with that. No additional behavioral details are given, but given the annotations, the tool's safety is well-covered.

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, one sentence, with no redundant 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 description sufficiently explains the tool's function for a simple version query. No output schema is present, but the description implies a version information return, which is appropriate for the tool's simplicity.

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 schema coverage is complete. There are no parameters to describe, so no additional parameter semantics are 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 shows current MCP platform and adapter versions, using the verb 'Show' and specifying the resource. It is distinct from sibling tools like authenticate or marketplace, which have 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 description does not provide any conditional usage guidance or mention when to prefer this tool over alternatives. It lacks explicit context on typical use cases or prerequisites.

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, so the safety profile is clear. The description adds valuable context by enumerating what the state includes, going beyond the annotations to explain the returned details, though it does not mention any potential side effects (none expected).

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 primary purpose ('Returns the current toolkit state') and then enumerates the contents. No wasted words or 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?

Given the tool's simplicity (no parameters, no output schema, strong annotations), the description fully covers the purpose and return contents. It is complete for an informational read-only tool, requiring no additional elaboration.

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?

There are zero parameters, so the baseline is 4. The description does not need to explain parameters, and the schema is trivially complete. The description itself adds no parameter-specific info 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 the tool returns toolkit state, listing specific components (installed MCPs, connection status, accounts, number of catalog tools). It uses a specific verb 'Returns' with a defined scope, and it's distinct from sibling tools that perform actions like authenticate or 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 retrieving state information but does not explicitly state when to use this tool versus alternatives or exclusion criteria. Siblings like show_version might overlap in utility, but no guidance is provided to disambiguate.

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