CRM

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

Annotations already declare mutation, idempotence, and non-destructive nature. The description adds valuable context about permanence (non-expiring via config vs session-only) and the two-step workflow. It does not contradict annotations, and the added details are useful but not exhaustive (e.g., no mention of exact return values or failure modes).

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 dense sentence but remains efficient, covering all key points without fluff. It is front-loaded with relevance and packs multiple instructions into a compact form. Slightly long but not wordy; could be split for readability, but maintains conciseness.

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 and absence of an output schema, the description adequately covers the workflow: how to invoke, what the no-args call returns (a link), and the two authentication modes. It does not describe error handling or explicit success responses, but for a simple auth tool this is sufficient.

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 an optional 'token' string with no description. The tool description fully clarifies that 'token' is the JWT from the browser, and explains that omitting it yields the login link. This completely compensates for the 0% schema description coverage.

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: authentication for IDE agents. It explains the flow of logging in via browser and obtaining an access token, and distinguishes itself from sibling tools by being the sole authentication entry point. The verb 'authenticate' plus the explicit context makes it 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?

Provides explicit usage patterns: call with no args to get a login link, then call with the token after the user pastes it. It also recommends a permanent config-based approach versus session-only, giving clear guidance on when to use each mode. This is more prescriptive than typical tool descriptions.

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 valuable behavioral details beyond the readOnlyHint annotation, such as the exact response structure (authenticated:true, empty pending[], connect_url, per-install URLs). It does not mention any side effects, but the annotation already indicates it's read-only and idempotent, so 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?

Two sentences: the first states the core function, the second explains the two state-dependent outcomes. No redundant phrasing, well structured, and front-loaded.

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 explains the two possible response scenarios and mentions URLs, which is adequate for a simple status tool with no output schema. However, it does not detail the structure of the URLs or any other fields, which could be slightly more explicit.

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 correctly does not attempt to explain parameters, and the schema already has no properties to cover.

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, with specific behavior for connected vs missing credentials. This distinguishes it from siblings like authenticate, which likely performs authentication rather than reporting status.

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 when checking connection status, but does not explicitly name alternatives or exclusions. It provides context such as the behavior when credentials are missing, which helps decide when to call it, but no direct comparison to 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?

As anotações já indicam readOnlyHint=false e destructiveHint=false, mas a descrição além disso revela o side-effect de que registros antigos não receberão a nova key, e enumera os tipos permitidos. Isso agrega contexto comportamental para além das anotações.

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 descrição é curta, começa com a ação principal e traz exatamente as informações centrais: propósito, a ressalva de migração e os tipos disponíveis. Não contém palavras desnecessárias nem repetições.

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?

Para uma ferramenta sem output schema e com 10 parâmetros, a descrição apenas cobre o comportamento principal e tipos. Faltam detalhes sobre vazio de parametros opcionais, relação com objetos e possíveis validações ou erros, o que impede a descrição de ser plenamente completa.

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?

A cobertura de params no schema é 0%, mas a descrição compensa parcialmente ao listar os tipos válidos do campo `type` e ao evidenciar `key` e `object` no texto. Parâmetros opcionais como `unique`, `indexed`, `required`, `options`, `relation` e `account` não são explicados na descrição.

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?

A descrição define claramente o propósito: 'Adiciona um CAMPO custom a um objeto', com verbo específico e recurso, diferenciando de ferramentas irmãs como crm_remove_field, crm_update_field e crm_define_object. A frase sobre migração também adiciona especificidade.

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?

A descrição deixa claro em que contexto usar (adicionar um campo custom) e expressa uma condição importante: 'sem migração; registros antigos ficam sem a key'. Porém, não cita explicitamente alternativas como crm_update_field ou crm_remove_field, então não chega 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?

The description adds useful behavioral context beyond the annotations: storage validates the real size, the file is marked as ready, and usage is counted. Since readOnlyHint=false already signals mutation, this extra detail meaningfully characterizes side effects.

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 compact and front-loaded: the main action, sequence, and side effects are in the first sentence, and bulk support is a separate brief note. No filler or redundant restating of the tool name.

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 confirmation tool, the description covers the purpose, prerequisite step, side effects, and bulk option. It does not mention account handling or error conditions, but this is not critical for basic tool selection and 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?

Schema description coverage is 0%, so the description must compensate for parameter understanding. It explains that file_ids enables bulk execution, but it does not clarify the account parameter or the relationship/behavior between file_id and file_ids. This is only partial compensation.

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 ('Confirma o upload') and identifies the exact context: after the PUT to upload_url. It also explains the resulting state changes (marks ready, counts usage), which clearly differentiates it from sibling upload-related tools like crm_upload_file or crm_upload_from_url.

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 clearly states when to use the tool: after performing the PUT to upload_url. It also notes bulk support via file_ids for batched execution. However, it does not explicitly name alternatives or exclusion cases, though the sequencing with sibling tools is strongly 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 indicate readOnlyHint=false and destructiveHint=false, so the description does not need to repeat that this is a write operation. The description adds context about the data format (JSON object/array) but does not disclose other behavioral aspects like idempotency, return value, or error behavior. This is acceptable given the annotations exist, but it doesn't exceed them much.

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, concise, front-loaded with the verb, and provides examples inline. Every sentence adds useful information without fluff or repetition.

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 create tool with 5 parameters and no output schema, the description covers the essential use case (object + data/records) but omits account and metadata. It also lacks information about return values or error handling. While not overly complex, the incomplete parameter coverage prevents a higher score.

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 coverage is 0%, so the description must explain parameters. It clarifies 'object', 'data' (JSON object), and 'records' (JSON array), adding meaning beyond schema's plain strings. However, 'account' and 'metadata' are not explained, leaving gaps. Overall, it adds value for the core parameters but isn't fully comprehensive.

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 creates one or multiple records of an object, using the verb 'Cria' (creates) and specifying the resource (object). It distinguishes itself from update/delete/get by the explicit create action, and even provides example object names like 'contact' and 'deal'.

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 on how to use the tool: for a single record, pass 'object' and 'data'; for multiple, use 'records'. It does not explicitly mention when not to use this tool or name alternatives, but the context is sufficient for an agent to infer its use case (create vs. update/delete).

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 it's not read-only and not destructive. The description adds that creating the object yields automatic CRUD/API, which reveals the side effect of object creation and API exposure. It doesn't describe reversibility or idempotency, but with annotations present, this is acceptable. The effect is clearly stated, adding value 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, front-loaded with the primary purpose. It avoids fluff and directly states the key parameters and their formats. Every sentence contributes meaning, and there is 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?

For a tool that creates a custom object with optional field definitions, the description conveys the high-level outcome (CRUD/API) but lacks details on the exact format of 'fields', the meaning of 'module', 'account', and 'display_field', and what the response contains. Since there is no output schema, these gaps affect completeness. It adequately covers the main creation flow but leaves advanced configuration undocumented.

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 coverage is 0%, so the description must compensate. It explains 'key' (api name with allowed characters), 'label', and 'fields' (JSON array of field definitions). However, it omits 'module', 'account', and 'display_field', which are not described anywhere. This partial coverage adds meaning for the most important parameters but leaves three unexplained, so it's adequate but not comprehensive.

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 creates a custom object in the CRM beyond the standard contact/company/deal, and that it gains automatic CRUD/API. This distinguishes it from record creation tools (crm_create_records) and object management tools (crm_update_object, crm_delete_object). The verb 'Cria' is specific and the resource is explicit.

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: use this when you need a custom object beyond standard ones. It mentions the need for 'key' and 'label' and optionally 'fields', giving basic usage direction. However, it does not explicitly mention alternatives like crm_add_field for adding fields to existing objects, nor does it state when not to use it. It's clear enough for the primary use case.

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 declare destructiveHint=false, but the description states it deletes files from storage and frees accounted space, which is inherently destructive. This contradiction makes the description unreliable regarding side effects. Annotation 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?

The description is a compact single sentence with no redundant wording. It is front-loaded and easy to read, though it sacrifices needed context for brevity.

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 3 undocumented parameters, no output schema, and contradictory annotations, the description is severely incomplete. It does not clarify parameter relationships, required vs optional fields, return behavior, or any prerequisites for deletion.

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 provides no parameter explanations. The phrase 'um ou mais arquivos' loosely hints at multiple ids vs a single file_id, but the 'account' parameter is completely unexplained. The tool fails to compensate for the schema's missing 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?

The description uses a specific verb 'Remove' and resource 'arquivos' (files), and adds the clarifying side effect 'apaga do storage e libera o espaço contabilizado'. This clearly distinguishes it from siblings like crm_list_files, crm_get_file, or crm_unpublish_file.

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 permanent deletion from storage, but provides no explicit guidance on when to choose this tool over alternatives like crm_unpublish_file or crm_delete_records. No exclusions or prerequisite conditions are stated.

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 declare destructiveHint=false, but the description says 'Remove' and advises using delete_records:true to 'delete everything', which is clearly destructive. This is an annotation contradiction. Beyond that, the description does not disclose other behaviors like irreversibility, side effects, or required permissions, and with annotations not covering destruction, it fails to provide necessary transparency.

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, concise sentence with two clear clauses. It wastes no words, front-loads the primary action, and provides the key operational detail. Perfectly sized for the purpose.

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 destructive nature, the absence of return information, error cases, or confirmation of irreversibility is a significant gap. The annotation contradiction further undermines completeness. The description is adequate for a simple delete but insufficient for a tool that can delete records en masse, especially without any output schema or safety disclosures.

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 explains 'object' as a custom object and 'delete_records' as a flag to delete associated records, but does not explain 'account'. This adds partial meaning but leaves one parameter undocumented, so it only partially compensates 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 clearly states the tool removes a CUSTOM object, explicitly excluding system objects. This distinguishes it from sibling tools like crm_delete_records (which deletes records) and crm_update_object (which modifies objects). The verb 'Remove' and resource 'object' are specific and 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?

The description provides clear context: it is used to remove custom objects, with an exclusion for system objects. It also gives explicit guidance on using the delete_records parameter to delete associated records. However, it does not explicitly compare with alternatives like crm_delete_records or crm_update_object, though the context implies when to choose this tool.

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 says 'Remove' (destructive) while annotations set destructiveHint=false, directly contradicting. No additional behavioral context is given, such as irreversibility, permissions, or impact on related data, making the tool's actual behavior ambiguous for agents.

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 fluff. It conveys the core action efficiently, though it is terse and omits necessary details.

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 deletion tool with no output schema and contradictory annotations, the description fails to provide essential context: it does not explain idempotency, failure outcomes, or account scope. The minimal description leaves agents guessing about side effects and dependencies.

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 must compensate. It clarifies 'ids' (one or more records) and 'object' (de um objeto), but leaves 'account' unexplained. The mapping is partial and does not fully clarify 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 specifies the action ('Remove um ou mais registros') and the resource ('de um objeto por id'), distinguishing it from sibling delete tools like crm_delete_file and crm_delete_object. It directly addresses 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?

No guidance is provided on when to use this tool versus alternative deletion tools or other record operations. The description only states the action without contextualizing usage scenarios or 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?

The annotations already declare readOnlyHint and idempotentHint true, so the tool's safety profile is established. The description adds behavioral context by stating that it returns the full schema (objects, fields, kanban), which is beyond the annotations. It does not contradict any annotations and provides a clear expectation of the tool's output.

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 model of conciseness: two short sentences, front-loaded with the primary purpose and followed by an explicit call-to-action. Every word serves a purpose, and the bolded 'CHAME ISTO PRIMEIRO' adds useful emphasis without clutter.

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 describe-type tool with strong annotations, the description covers the essential information: what is described (schema), the granularity (fields with properties), and the intended usage pattern (call first). The only gaps are the unexplained 'account' parameter and lack of detail on output format, but these are minor given the tool's simplicity and the descriptive power of the annotations.

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 is one optional parameter 'account' that is completely undocumented. The description does not explain what 'account' refers to or how it affects the output. Since schema description coverage is 0%, the description should compensate but it remains silent about this parameter, leaving the agent guessing.

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: it describes the CRM schema including objects and their fields. It specifies the scope (contact, company, deal, custom) and details (key, type, required, options, relationships) and distinguishes itself as a discovery tool rather than a data manipulation tool. It is clearly differentiated from siblings like crm_list_objects or crm_get_object by focusing on schema introspection.

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 instructs the user to call this tool first before creating or reading records, establishing a clear usage pattern. It uses an imperative 'CHAME ISTO PRIMEIRO' to signal priority, and the context of when to use it (before any create/read operations) is unambiguous. Although it does not name alternative tools, it effectively communicates the recommended sequence.

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, so the safety profile is covered. The description adds valuable behavior beyond annotations: the returned URL is presigned and expires in a few minutes, and it supports batched execution via file_ids. It does not contradict any annotations and provides context about the output format and expiration.

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: the first states the core function and expiration, the second introduces bulk support. It is front-loaded with the main purpose, contains no filler, and fully earns its place. Perfectly concise.

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 low complexity (single action, read-only) and the presence of good annotations (readOnly, idempotent), the description covers the key aspects: it generates a URL, the URL expires, and bulk mode exists. However, it lacks detail on the exact format of the response (e.g., whether it returns a single URL or a list for bulk) and does not explain the 'account' parameter. Since there is no output schema, some gaps remain, but the essentials are covered.

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 has no parameter descriptions (0% coverage), so the description must compensate. It only explains the file_ids parameter for bulk execution, omitting the meaning of 'account' and the relationship between file_id (required) and file_ids (optional). This leaves ambiguity about whether file_id is needed when file_ids is used, and what the response looks like. The description adds minimal value over the parameter 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's purpose: generating a presigned GET URL for a file. The verb 'gera' (generates) and the resource 'URL presigned de download' are specific, and the mention of bulk support adds a distinctive feature that separates it from sibling tools like crm_get_file (direct file content) and crm_delete_file.

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 some context (URL expires in minutes) but does not explicitly state when to choose this over alternatives. It does not mention exclusions or use cases like sharing vs. direct retrieval, nor does it reference sibling tools. The bulk support hint gives a conditional use case but lacks a clear comparison with other file-related 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 cover read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by listing the returned metadata fields and explicitly noting bulk/batched execution via file_ids, going beyond what annotations state.

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 short lines immediately communicate the core purpose and the bulk capability. There is no redundant content, and the most important information is front-loaded.

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 main purpose and bulk behavior, and the rich annotations provide the safety profile. However, without an output schema and with an unexplained account parameter, plus a possible ambiguity between required file_id and optional file_ids, the tool is not fully self-contained for an agent.

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 explain the parameters, but it only clarifies file_ids for bulk execution. It does not explain file_id versus file_ids, nor the purpose of account. The schema names alone are insufficient for an agent to confidently construct all valid calls.

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 resource as a file and explains it returns metadata (name, size, content_type, status, attachment), which clearly distinguishes it from sibling tools like crm_download_file or crm_list_files. However, it lacks an explicit verb such as 'retrieves' and instead uses a noun phrase, so it is slightly less explicit than ideal.

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 metadata focus implies the tool is used when a caller needs file metadata rather than file content, and the bulk-support note indicates a batch use case. There is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named.

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 non-destructive behavior. The description adds useful behavioral context beyond that: it details one object and lists the specific attributes returned, which helps set expectations without contradicting 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?

Two short, front-loaded sentences deliver the core purpose and scope with no filler. Every word adds value, and the sibling distinction is compactly integrated.

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 detail tool with strong annotations and only two parameters, this description is largely complete: it states the operation, scope, and output content. The main gap is the undocumented parameter semantics, especially 'account', but overall the tool context is well covered.

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 should compensate for undefined parameters, but it does not explain the 'object' parameter format or the optional 'account' parameter at all. 'UM objeto' only weakly implies that 'object' selects the object, and 'account' is completely unaddressed.

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 ('Detalha') and resource ('UM objeto'), and enumerates the returned content: label, kanban, and all fields with key/type/required/options/relation. It also distinguishes itself from the sibling crm_describe by calling itself a focused 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 phrase 'Versão focada do crm_describe' clearly positions this tool as the detailed single-object variant of crm_describe, giving the agent context for when to choose it. However, it does not explicitly state when not to use it or mention other alternatives.

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 read-only behavior is covered. The description adds that one or more records are fetched by id, but does not disclose behavior for missing ids, partial failures, or account scoping.

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 filler. Every word adds meaning, making it highly concise and easy to parse.

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 output schema and no parameter descriptions, the tool needs a richer description. The current text leaves important gaps around the account parameter, response shape, and behavior when ids are invalid or missing, so it is not fully adequate for an agent to invoke confidently.

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 roughly maps 'object' and 'ids' via 'registros de um objeto por id', but it fails to explain the optional 'account' parameter or the expected id format. This is only partial compensation for the missing parameter 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 resource and action: retrieving one or more records of an object by id. It distinguishes from mutation tools and from list/search at a basic level, though it does not explicitly contrast with crm_get_object or crm_related_records.

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 when fetching records by id, but provides no explicit when-to-use guidance, prerequisites, exclusions, or alternatives. It does not mention when to prefer crm_get_object, crm_related_records, or crm_search.

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 meaningful behavioral transparency beyond the annotations: it explains that many-relationships add to a set, single-relationships set a target, and that batches are supported. It does not contradict the annotations; readOnlyHint=false is consistent with a linking mutation.

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 and well-structured: it front-loads the core purpose, provides a concrete example, then adds cardinality and bulk support details. Every sentence adds value without restating the schema or annotations.

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 a mutation tool with 7 parameters, 0% schema descriptions, and no output schema. The description covers the primary use case and bulk behavior, but it leaves some context empty: what account/object mean, how errors behave, and what the caller should expect after execution.

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 0% parameter description coverage, so the description has to compensate. It does clarify ids/target_ids for bulk execution and mentions the relationship field semantics, but it leaves important parameters like account, object, and singular/plural relationships under-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 states the core action: linking a record to another via a relationship field, with a concrete CRM example (contact to company). It also differentiates behavior for 'many' versus 'single' relationships and distinguishes itself from siblings like crm_unlink_record.

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 conveys when to use the tool: when linking records, including cardinality-specific behavior and bulk support via ids/target_ids. It does not explicitly name alternatives or exclusion cases, such as 'use crm_unlink_record to remove links,' but the context is otherwise 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 already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the return fields (id, label, is_default) and the meaning of is_default, which is not available from annotations alone. No contradiction exists; the description complements the safety profile.

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, concise sentence (or two clauses) that front-loads the main action ('Lista os CRMs conectados') and then provides essential details about return fields and default behavior. No redundant information or filler; every phrase 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?

Given the tool has no parameters and no output schema, the description provides sufficient detail by enumerating the output fields (id, label, is_default) and explaining the is_default semantics. It covers the necessary information for an agent to use the tool correctly, and the annotations cover the safety aspects.

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 description has no parameter semantics to add. With no schema properties, the baseline is 4. The description does not need to explain parameters but provides relevant output semantics, which is acceptable given the tool's simplicity.

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 lists connected CRMs with specific fields (id, label, is_default). It uses a specific verb 'Lista' and a resource 'CRMs conectados', distinguishing it from sibling crm_* tools that operate on records, objects, files, etc. No ambiguity.

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 usage context by explaining that is_default is true when only one CRM exists, obviating the need to pass an 'account' parameter to other tools. It does not explicitly state when to use or not use alternatives, but the context implies this tool is for discovering available accounts before other operations. It gives clear contextual guidance without explicit 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, non-destructive operation. The description adds useful context about bulk execution (record_ids) and the optional filtering, which is beneficial. However, it does not disclose how results are returned (e.g., list format, pagination) or whether any limits apply, but the bar is lower due to annotations, so 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 concise: two short paragraphs. The first sentence clearly states the function and optional filter, and the second mentions bulk support. It is front-loaded with the key information. However, the line break after the first sentence is somewhat awkward but not problematic. The content is efficient and earned.

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 (4 optional parameters, bulk support) and the lack of an output schema, the description could be more complete. It explains the purpose and optional filtering, but does not describe what the returned files look like (beyond naming attributes) or how the bulk mode behaves (e.g., response aggregation). Annotations cover safety, but the lack of output schema and parameter clarity leaves gaps for an agent to invoke 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?

The input schema has 4 parameters with 0% description coverage, meaning the schema provides no type info beyond 'string' or 'array of strings'. The description partially compensates by mentioning that filtering is optional and that 'record_ids' enables batch execution, but it does not explain the difference between 'record_id' and 'record_ids' (singular vs plural), nor the roles of 'object' and 'account'. The description's mention of 'objeto/registro' gives vague context, but fails to fully clarify parameter meaning, so it does not compensate for the low coverage.

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 the tool lists CRM files with specific attributes (id, nome, tamanho, status) and optional filtering by object/record. This clearly distinguishes it from sibling tools like crm_get_file (which likely retrieves a single file) and crm_download_file (which downloads the file content), and from crm_list_records (which lists records, not files).

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 on when to use the tool (to list files, optionally filtered by attachment) and mentions bulk support via record_ids. However, it does not explicitly state when not to use it or mention alternatives for filtering by other criteria, such as crm_search. The mention of bulk support adds functional context, but exclusions are absent.

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, which cover safety. The description adds context about what attributes are returned and that it's a lean variant of crm_describe. This adds some value but no deeper behavioral traits (e.g., pagination, ordering, errors). With annotations present, 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, compact sentence that front-loads the action and resource, and avoids all redundancy. Every word is informative, making it highly concise.

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 (lists objects) and has good annotation coverage, but the unexplained 'account' parameter is a critical gap. There's no output schema to clarify return values, so the description should at least clarify the parameter scope. The lack of any parameter guidance brings completeness down, despite 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 schema has one parameter (account) with 0% description coverage, and the description does not mention it at all. The agent has no clue what 'account' refers to (e.g., account name, ID, optional/required). The description fails to compensate for the schema gap, rendering the parameter ambiguous.

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 lists CRM objects with specific attributes (key, label, module, kanban) and explicitly distinguishes itself from crm_describe by noting it's a lean version without fields. This is a specific verb+resource with clear scope.

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 it: when you need a simple list of objects without field details, as it positions itself as an alternative to crm_describe. However, it doesn't explicitly state exclusions or alternative conditions, so it's clear but not with explicit when-not 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 provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds value by detailing the exact JSON filter format with supported operators (eq, ne, gt, gte, lt, lte, in, nin, contains, exists), which goes beyond the bare schema. It does not contradict any 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 sentence that front-loads the primary action ('lists records of an object') followed by the essential filter details. Every word is necessary, and it avoids any fluff or repetition. It is concise and well-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?

Given that there is no output schema, the description does not explain the return format or pagination specifics (e.g., how offset/limit work, default values). It also does not clarify the account parameter or sort syntax. While the core purpose and filter format are covered, the overall context is incomplete for a tool with 6 parameters, especially since some are not described. The description would benefit from mentioning the response shape or pagination 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. It explains the filter parameter in detail, including syntax and operators, which is the most complex parameter. However, it does not describe the sort format (e.g., field, direction), pagination behavior (limit/offset defaults), or the account parameter. Despite this, the detailed filter guidance provides meaningful semantic value.

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 'Lista registros de um objeto' (lists records of an object), which is a specific verb+resource. It clearly indicates a read operation with filtering, sorting, and pagination. This distinguishes it from sibling tools like crm_create_records or crm_delete_records, and even from crm_get_records which likely returns individual records.

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 used for listing records of an object, but it does not provide explicit guidance on when to use this over alternatives like crm_search or crm_get_records. There is no mention of exclusions or alternative tools, so the context is clear but no differentiators are given.

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 provide readOnlyHint=false and destructiveHint=false, already indicating a non-destructive write. The description adds that it validates the stage and supports bulk execution via ids, which are useful behavioral details beyond what annotations convey.

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 primary purpose and followed by a bulk note. No wasted words or unnecessary details.

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 no output schema and 0% param coverage, the description lacks essential details like error handling, return values, and parameter relationships. It does not explain behavior on invalid stage or how 'account' is used, making it incomplete for a mutation tool with 5 params.

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 has 0% parameter coverage, so description must compensate. It mentions 'stage' and 'ids' for bulk, but does not clarify the relationship between 'id' and 'ids', the meaning of 'object' beyond the generic 'kanban object', or the role of 'account'. Key parameters remain ambiguous.

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?

Description clearly states it moves a record (e.g., deal) of a kanban object to another stage, validating the stage. This specific verb+resource+context distinguishes it from generic record updates like crm_update_records.

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 moving stages but does not explicitly mention alternatives or when not to use. No exclusions or guidance on choosing this over sibling tools like crm_update_records.

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?

Even though annotations already convey that this is not read-only, not destructive, and not idempotent, the description adds meaningful behavior: the object remains private in storage, the token is the revocable key, public-view egress is billed, and bulk execution via file_ids is supported. No contradiction with annotations exists.

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 compact and front-loaded: the first sentence states the core action and output, followed by a practical URL example, key behavioral caveats, and a brief bulk-support note. Every sentence earns its place with no 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?

Given that there is no output schema and annotations are minimal, the description covers the main return value (stable URL), use case, reversibility, egress accounting, and bulk behavior. It is missing context around the account parameter and possible error/prerequisite conditions, but it is sufficient for an agent to select and 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?

Schema description coverage is 0%, so the description must compensate. It explains that file_ids enables batched execution, which adds real meaning. However, it does not clarify the optional account parameter or the relationship between file_id and file_ids, leaving part of the parameter surface ambiguous.

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 makes a file public and returns a stable embeddable URL, which distinguishes it from sibling tools like crm_unpublish_file, crm_get_file, and crm_delete_file. It uses a specific verb plus resource and includes a concrete use case (embedding a thumbnail).

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 use (embedding in a site) and points to crm_unpublish_file as the revocation mechanism, giving useful orientation. It does not explicitly contrast with other file-related tools or state when not to use it, so it stops short of full alternative 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, covering the safety profile. The description adds useful behavioral details such as following relationship fields, returning all or a specific field's target records, and supporting batched ids, but does not disclose pagination, authorization, or error behavior.

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 with no filler. The core action is front-loaded, and the second sentence adds the bulk-support behavior efficiently.

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 has five parameters, no output schema, and no schema-level parameter descriptions. The description covers core behavior and the general return concept, but omits details such as id/ids mutual exclusivity, account usage, and an outline of the return structure.

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 clarifies `field` as a filter for one relationship field and `ids` as batch support, but leaves `object`, `id`, and especially `account` implicit without explaining their roles or how they interact.

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 'Resolve os registros relacionados de um registro', which clearly states a specific verb and resource: resolving related records. It further distinguishes itself from siblings like crm_get_records and crm_list_records by explaining that it follows relationship fields and returns target records.

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 relationship traversal is needed) and mentions bulk support, but it does not explicitly contrast it with alternatives like crm_get_records or crm_search. No exclusions or prerequisites are stated.

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 minimal (readOnlyHint false, destructiveHint false), so the description must carry the burden. It adds valuable context: soft-delete behavior (removes schema but preserves values) and the constraint that system fields cannot be removed. This goes beyond annotations and helps set expectations.

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 front-loads the core action and important caveats (soft-delete, system field restriction). Every word adds value; 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?

The tool is destructive (although soft-delete), and the description lacks crucial operational details: what happens if the field doesn't exist, how to specify the object/key, error handling, or confirmation of removal. The low parameter coverage and lack of output schema make this description insufficient for safe self-service use.

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 lists three parameters (object, key, account) with no descriptions, and schema coverage is 0% because the description does not explain any of them. The description does not mention what 'key' or 'object' represent, leaving the agent to guess. With low schema coverage, the description should compensate but fails to do so.

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 removes a CUSTOM field, with a specific verb and resource, and specifies the soft-delete nuance and restriction on system fields. This distinguishes it from sibling tools like crm_add_field or crm_update_field.

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 removing custom fields and explicitly states system fields cannot be removed, but it does not reference alternative tools or provide exclusions beyond system fields. It lacks guidance on when not to use this tool compared to crm_delete_object or crm_update_field.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, which already disclose the safe, non-destructive nature. The description adds the behavior of searching by name/title/values and optional object restriction, but does not disclose details like pagination, result format, or account scoping beyond the parameter. Since annotations cover the main behavioral traits, a score of 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 two concise sentences in Portuguese, front-loaded with the core purpose and a clear optional parameter. Every word earns its place, with no fluff or repetition of schema details.

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 a read-only search with 4 parameters and no output schema, the description explains the essential search behavior and the key optional filter (object). However, it does not clarify the behavior of 'limit' or 'account', and with no output schema, it could have mentioned return format or pagination. This is adequate but not fully comprehensive.

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 does explain that 'object' restricts the search scope and that 'q' is the main search term. However, it does not add meaning for 'limit' or 'account' beyond what their names imply. The description adds value for 'q' and 'object' but leaves other parameters unexplained, so a baseline 3 is justified.

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 ('Busca textual') and resource ('nos registros'), clarifying it performs a text search across CRM records. It distinguishes itself from sibling tools like crm_get_records and crm_list_records by emphasizing the textual search aspect and optional object restriction.

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 text-based searching and optional filtering by object type, but does not explicitly state when to use this versus alternatives like crm_list_records or crm_get_records. It provides clear context for the search behavior but lacks explicit when-not 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 indicate non-read-only, non-idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it clarifies that unlink modifies relationship references rather than deleting records, explains behavior per relationship cardinality, and discloses bulk support. It does not mention failure modes or return behavior, but the provided safety profile is reasonably complete.

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 appropriately short and front-loaded with the core function, followed by relationship-specific semantics and then bulk support. Every sentence contributes new information without 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?

Given the tool has 7 parameters, 0% schema description coverage, no output schema, and no parameter descriptions, the description is incomplete. It covers the core unlinking concept and bulk support, but does not explain required fields like object, id, and field, nor what the operation returns or how errors are handled.

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, but it only partially does so. It clarifies target_id, ids, and target_ids in the context of bulk/unlink behavior, but leaves critical parameters like object, id, field, and account unexplained. In particular, the relationship between id and ids, and the exact role of field, remain ambiguous.

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: 'Desfaz uma relação' (breaks a relationship), with concrete semantics for many ('remove o target_id do conjunto') and single ('limpa o campo') relationships. This distinguishes it from sibling tools like crm_link_record and crm_delete_records, as it is explicitly about unlinking rather than deleting records.

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 useful context on when to use the tool by explaining how it behaves for 'many' vs 'single' relationships and by noting bulk execution support. It does not explicitly name alternatives or state when not to use it, but the context is clear enough to guide selection among 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?

The description adds context beyond the annotations by stating the immediate effect: 'the token stops working immediately.' It also clarifies that this affects the public link, not the file itself. Annotations already indicate a mutation (readOnlyHint=false) and non-idempotent behavior, so the description adds valuable behavioral detail without contradicting the structured data.

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, consisting of two sentences: one for the primary purpose and another for bulk support. It is front-loaded with the core behavior and contains no unnecessary words or repetition.

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 three parameters and no output schema, the description covers the main action and bulk support but misses details such as parameter relationships, prerequisites (e.g., file must be published), and what happens if the file is already unpublished. It is adequate but not fully complete for an agent to invoke it without additional assumptions.

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 explains that file_ids enables batch execution, giving meaning to that parameter. However, it does not explain the 'account' parameter or the relationship between file_id and file_ids (e.g., whether they are exclusive or complementary). This leaves important semantic gaps.

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 action: 'Revokes the public link of a file (the token stops working immediately).' This uses a specific verb and resource, and it is easily distinguished from sibling tools like crm_publish_file (the opposite action) and crm_delete_file (deletes the file itself).

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 this tool: when you need to revoke a public link or token. It also notes bulk support for file_ids, indicating use for batched operations. However, it does not explicitly mention alternatives or when not to use it, so it falls short of full 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 indicate this is a mutating, non-read-only operation, and the description adds meaningful behavioral constraints beyond that: type changes are restricted to safe widening, and lossy changes are blocked. It does not cover all possible side effects or permissions, but it discloses the most important operation-specific rule.

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 compact and front-loaded: the first clause states the action and scope, followed by a list of editable attributes and a focused warning about type changes. Every sentence earns its place with no redundant 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?

The description is reasonably complete for a mutation tool, especially with the type-change safety rule, but the tool has 10 parameters and no output schema. Missing semantics for required identifier parameters, the 'account' field, and any return/confirmation behavior leave gaps for an agent trying to invoke it 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?

With 0% schema description coverage, the description carries the burden of explaining parameters. It maps several parameters (label, required, visible, position, options, indexed) and provides a type-change example, but it leaves the required 'object' and 'key' identifiers unexplained and does not clarify the 'account' or 'options' formats.

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 edits a field and lists the editable attributes (label, required, visible, position, options, indexing), distinguishing it from sibling tools like crm_add_field and crm_remove_field. The verb 'Edita' plus the specific resource 'campo' makes the purpose explicit.

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 practical guidance on when not to use the tool: type changes are only allowed for safe widening, and lossy changes are blocked with the advice to create a new field and migrate. It does not explicitly name alternative sibling tools, but the when-not-to-use logic 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 already indicate this is a mutation (readOnlyHint=false) and non-destructive. The description adds useful constraints—the key is immutable and system/custom objects are supported—but it does not disclose side effects, permission needs, or what happens when editing system objects.

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 uses a colon to list editable fields and a parenthetical for the key constraint. It is concise, well-structured, and free of 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 metadata update tool, the description covers purpose, scope, editable fields, and a key limitation. Still, it omits clarification of the object/account parameters and potential implications of editing system objects, so it is not fully complete.

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 adds meaningful semantic meaning for label, display_field, module, and kanban, and warns that the key cannot be changed. However, it leaves the required 'object' parameter and the optional 'account' parameter semantically unexplained.

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 'Edita um objeto' (edits an object) and enumerates specific editable attributes: rótulo, campo de exibição, módulo, and kanban config. This clearly distinguishes it from siblings like crm_define_object, crm_delete_object, crm_update_field, and crm_update_records.

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 states that it applies to both system and custom objects, which gives some usage context. However, it does not explicitly say when to prefer this tool over related tools like crm_update_field or crm_update_records, nor does it mention exclusions 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?

The description discloses important behavioral nuances beyond annotations: it specifies partial merge ('merge parcial'), that null values remove fields ('null apaga o campo'), and batch support via ids. These traits are not provided by the annotations (which only indicate non-read-only, non-idempotent, non-destructive) and give the agent essential knowledge about side effects and semantics. It does not contradict annotations and adds value.

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 that deliver the main action, parameter usage, and bulk support without redundancy. It is front-loaded with the core purpose and each sentence earns its place, providing essential information without unnecessary elaboration.

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 complexity (7 params, no output schema), the description adequately covers the primary workflow: single partial update with null deletion, multi-update via array, and bulk via ids. It misses semantics for `account` and `metadata`, which may be optional or context-specific, but overall it provides sufficient context for an agent to understand and invoke the tool correctly in most scenarios.

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 schema description coverage at 0%, the description carries the burden of explaining parameters. It explains `object`, `id`, `data` (only fields to change, null deletes), `updates` (array of {id, data}), and `ids` for bulk. However, it omits any explanation for `account` and `metadata`, leaving those parameters undefined. The description adds value for core parameters but is incomplete, missing two of the seven.

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 'Atualiza um registro (merge parcial) por id' (Updates a record (partial merge) by id), giving a specific verb and resource with the key semantic of partial merge. This clearly distinguishes it from sibling tools like crm_create_records or crm_delete_records by focusing on update semantics. The mention of null deletion and bulk support further clarifies scope.

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 usage guidance by instructing to pass 'object, id e data' for single updates and 'updates' for multiple, plus 'Bulk support: accepts ids for batched execution.' This conveys when to use the tool for partial updates and bulk operations, though it does not explicitly compare with alternatives like create or delete, so it lacks explicit exclusions. The context is clear enough for an agent to infer use cases.

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 the two-stage upload behavior, 200 MB size limit, and bulk support, which go beyond the annotations. Annotations already convey non-read-only and non-destructive intent, and the description does not contradict them. It could add failure semantics or auth requirements, but the core behavior 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 compact and front-loaded with the primary purpose, then provides workflow and optionality. Every sentence earns its place; no filler 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 no output schema, the description still covers the main return values (upload_url, file_id) and the mandatory follow-up. It omits details like parameter interaction rules and possible conflicts between record_id and record_ids, but is fairly complete for the core upload flow.

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 has 7 parameters with 0% description coverage, so the description must compensate. It clarifies object/record_id/record_ids and implies filename/size, but leaves content_type and account unexplained and does not specify the units for size. This is a significant gap for parameter usage.

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?

Description clearly states it starts a file upload, returns a presigned URL and file_id, and requires a follow-up PUT then crm_confirm_upload. The verb+resource is specific and distinguishes this tool from siblings like crm_confirm_upload and crm_upload_from_url.

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 an explicit workflow: PUT to the presigned URL, then call crm_confirm_upload. It also explains optional record attachment and bulk usage via record_ids. It does not explicitly contrast with crm_upload_from_url, but the intended usage context 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?

The description adds useful behaviors beyond the annotations: the platform downloads and stores the file, there is a 200MB limit, the file is returned ready, record attachment is optional, and record_ids enables bulk execution. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false), though it remains silent on specifics like account selection or output shape.

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 short, front-loaded, and well-scoped into a main explanation, optional behavior, and bulk support note. Every sentence adds useful information without unnecessary filler, and the formatting makes the tool's core behavior immediately visible.

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 has 7 parameters, no parameter descriptions in the schema, and no output schema, the description covers the main flow but not all important contextual details. It misses parameter semantics for account, filename, and content_type, and does not describe what shape the response takes or whether attachments require any pre-existing object context.

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?

While the schema has 0% description coverage, the description explains url, object+record_id attachment, and record_ids bulk support, which adds meaningful context. However, parameters like account, filename, and content_type are not explained at all, leaving gaps for an agent preparing calls to this 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 uses a specific verb and resource: 'Sobe um arquivo A PARTIR DE UMA URL' (uploads a file from a URL), and clarifies the platform downloads and stores it, up to 200MB. This clearly distinguishes it from sibling tools like crm_upload_file or crm_download_file by focusing on URL-based uploads without the agent holding the bytes.

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 explicitly describes when to use the tool: 'o jeito do AGENTE subir via API sem segurar os bytes' — the way for an agent to upload via API without handling raw file content. It also describes optional record attachment and bulk usage, but does not explicitly name alternatives like crm_upload_file, so it lacks exclusionary 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, destructiveHint=false, indicating a safe read operation. The description adds concrete details on the returned data (bytes, GB, file count, egress) and its role in billing, offering value 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 a single, tightly written sentence that covers the tool's purpose and key outputs. It avoids unnecessary fluff, front-loads the primary function (storage usage), and efficiently conveys billing relevance. Every clause contributes 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 has no output schema, so the description is the only source for return details. It lists the main metrics but lacks specifics on types, units, or structure (e.g., whether it returns JSON, exact field names). Given low complexity (1 param, no nested objects), the description is adequate for a basic understanding but leaves gaps for precise invocation, especially regarding the 'account' parameter.

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 only one parameter 'account' and 0% schema description coverage, the description should explain what 'account' refers to (e.g., account identifier). It does not mention the parameter at all, relying on the schema's type-only definition. The description fails to compensate for the lack of parameter documentation, leaving the agent guessing about expected input.

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 retrieves storage usage (database bytes, file bytes, total GB, file count, accumulated egress), and explicitly ties it to billing. This distinguishes it from sibling tools like crm_list_files or crm_get_records, which focus on individual items rather than aggregate usage metrics.

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 storage consumption and billing basis, but lacks explicit guidance on when to prefer this over alternatives like crm_list_files or crm_get_object. No exclusions or alternative mentions are provided, leaving the agent to infer its purpose from 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 say readOnlyHint=false and destructiveHint=false. The description adds substantial behavioral disclosure: invoke runs tools one-off even when not installed ('without adding the MCP to the toolkit'), returns a connect link when credentials are needed, and a checkout/top-up link when the wallet is empty (then 'you retry'). It also flags that writes require workspace owner/admin. 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 extremely dense and runs as one unbroken paragraph with no bullets or structural separation. Every sentence carries useful content, so content-wise it earns its place, but the wall-of-text format makes it hard to parse quickly; front-loading exists only in the opening clause.

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 23 unmapped params and no output schema, the description covers the primary flows (search/describe/invoke/install, billing, prompt library, permissions) in impressive depth. The main gaps are secondary actions (resume, immediate, tier_slug, cancel_reason formatting) that receive no explanation, leaving minor ambiguity.

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% with 23 parameters, so the description carries the full burden. It does a strong job explaining the action parameter and the core tool_id/arguments flow, plus prompt_* params for the library. However, many parameters (limit, mcp_id, tier_slug, immediate, resume, conversation, cancel_reason, report_context, etc.) are never mapped, leaving the agent to guess on secondary params.

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 marketplace as 'the in-platform catalog of every MCP/tool, AND the way to run them.' It specifies the verbs (search, describe, invoke, install, list_tools) and resources (MCPs, tools, prompts), and distinguishes itself from the CRM/authenticate siblings by emphasizing its role as a cross-tool catalog and execution router.

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 walks through the core flow explicitly ('action=search discovers MCPs by intent → describe returns one MCP's full profile → invoke RUNS that tool'). It gives direct when-to-use guidance: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT,' plus role boundaries for each action (subscribe/cancel for billing, report_bug for feedback, request_mcp when nothing fits).

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 non-read-only, idempotent, and non-destructive behavior. The description adds a useful behavioral hint by instructing to include the conversation array for reproduction, but it does not explain side effects like sending data, authorization needs, or response behavior beyond what the annotations convey.

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, front-loaded with the core purpose, and includes only the essential operational instruction. 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, with no output schema and few parameters, but the description leaves the `context` parameter ambiguous and does not mention expected output or confirmation after reporting. It is minimally complete for basic invocation but has clear 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?

Schema description coverage is 0%, so the description must carry the burden. It explicitly explains the `conversation` parameter's purpose and gives meaning to `message` through the main verb, but `context` is left unexplained. This is partial compensation, not full.

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 bugs, missing features, or feedback, using a specific verb and resource. This distinguishes it from unrelated sibling tools like CRM operations or authentication.

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 provides clear context for when to use the tool: when a bug, missing feature, or feedback needs to be communicated. It does not explicitly mention alternatives, but none of the siblings perform this function, so the usage context is well 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the scope (platform and adapter versions) but does not disclose additional behavioral details such as output format or network dependence, which would add value.

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 sentence of eleven words fully conveys the tool's purpose without any filler, repetition, or unnecessary 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?

For a zero-parameter, read-only, idempotent tool with good annotations, the description provides enough context to understand what the tool returns. However, since there is no output schema and no description of the result structure, a small amount of additional detail about the response could make it more complete.

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 there is nothing for the description to explain. The baseline of 4 applies, and no parameter-related gap exists.

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 clearly identifies the resource ('current MCP platform and adapter versions'). This makes the tool's purpose unambiguous and distinguishes it from sibling tools like toolkit_info and crm_usage, which have different scopes.

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?

No guidance is provided about when to use this tool versus alternatives, nor are any exclusions or conditions stated. For a simple read-only version check, context 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?

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds meaningful behavioral context by specifying exactly what 'toolkit state' contains: installed MCPs, connection statuses, connected accounts, and exposed catalog tool counts. This fully communicates the observable behavior without contradicting any annotation.

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 wastes no words. It starts with the action verb 'Returns,' immediately states the subject, and packs all relevant information into a succinct, readable list.

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 zero-parameter, read-only informational tool without an output schema, the description is complete: it covers what is returned, the scope of the state, and the level of detail. No additional explanation about side effects, prerequisites, or return formats is necessary given the annotations.

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 there is no parameter semantics for the description to add. The absence of parameters is self-evident from the schema, and the description appropriately focuses on the return value instead.

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') and names the exact resource ('current toolkit state') while enumerating the four concrete pieces of information delivered (installed MCPs, connection status, connected accounts, catalog tool counts). This clearly distinguishes it from sibling tools like show_version, crm_usage, or marketplace, which target different information.

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 makes it obvious when to call this tool: whenever an agent needs to inspect the current toolkit state or assess MCP connectivity and available accounts. It does not explicitly state when not to use it or name alternatives, but the context is clear enough that no competing sibling serves the same purpose.

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