iClips

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

The description adds useful behavior beyond the annotations: config header yields a permanent connection, while passing a token yields a session-only login, and no args returns a link. It does not fully spell out side effects or success/failure return values, but annotations already cover idempotency and non-destructiveness.

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 dense and front-loaded, with no fluff, but the long single sentence with parenthetical clauses and multiple alternatives could be structured into clearer separate instructions. Still, every part adds necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter auth tool with no output schema, it covers the no-arg return (the link), the token-paste path, and the persistent-config alternative. It doesn't state the response on a token success/failure, but the invocation guidance is sufficient for an agent to call 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 coverage, the description carries the full burden for the optional `token` parameter. It explains that token is a JWT/access token pasted by the user and how to pass it, compensating well for the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as MCP.AI authentication for IDE agents, with a concrete browser-login + access-token flow and two invocation paths (no args for a link, token for login). This specific verb+resource is unambiguous and easily distinguished from the unrelated calculo_* sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly differentiates the persistent config-header approach ('best... permanent, non-expiring') from the session-only paste/login path, and states exactly when to call with no args versus with { token }. This gives the agent clear selection criteria for both setup and invocation.

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 establish this is read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that by specifying the two main response states: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This helps an agent predict what to expect.

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, front-loads the core purpose, and then adds only the essential conditional details. Every sentence contributes meaningful information, and there is no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only status tool with no output schema, the description is complete enough. It tells the agent what information will be returned, what the success condition looks like, and what happens when credentials are missing. The low complexity means no additional guidance is required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the description does not need to explain any input semantics. The baseline of 4 applies because there is no parameter burden at all.

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: returning connection status and URLs. It distinguishes connect from its sibling authenticate by framing it as a status/read operation rather than an action, and the conditional output descriptions reinforce this.

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 clear that this is the tool to call when checking connection state or getting URLs. It does not explicitly mention alternatives like authenticate, but the context strongly implies connect is for status checking rather than initiating authentication, so usage is clear without being fully explicit.

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

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

Annotations already mark it read-only, idempotent and non-destructive. The description adds real behavioral facts: there is no filter or pagination and it always returns all active accounts. This is consistent with 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?

Three sentences with no filler: purpose and return fields, downstream usage, and constraints are each given a sentence. The most important scoping information appears first.

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 list, the description covers the returned fields and calling constraints well. However, the presence of an optional 'account' parameter that the description says is not a filter creates a completeness gap; an agent cannot be fully sure how to handle it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the only parameter 'account' is undocumented. The description's 'Não tem filtro nem paginação' implies the parameter does not act as a filter, but it never states whether the parameter is ignored, deprecated or used for something else.

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 names a specific operation ('Lista') on a specific resource ('contas bancárias ativas da agência no iClips') and enumerates returned fields. It is clear and precise, but it does not explicitly differentiate from the similar-sounding sibling iclips_list_accounts.

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 downstream guidance ('Use o id retornado como account_id ao filtrar iclips_financial_entries') and states the tool's no-filter/no-pagination behavior. It does not mention when to prefer this over iclips_list_accounts, so it stops short of full alternatives 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 mark this as read-only and idempotent, and the description reinforces this with 'Não existe escrita no financeiro'. It adds rich behavioral detail beyond annotations: date_field changes which date is filtered, entry date means due date for open items, payment date only returns paid items, and batch get reports errors per id. 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 long but well structured with an opening summary, an 'Ações' section, a use-case sentence, a return-value summary, and a final read-only note. The list action documentation is partly extraneous given the '[Flattened action: get]' marker, but it still helps contextualize the module. Overall, nearly every sentence contributes useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool with no output schema and no parameter descriptions in the schema, this description is unusually complete. It explains pagination, date filtering semantics, batch behavior, and even describes the returned shape (value, retained taxes, category, bank account, linked invoice, recipient, cost-center allocation). The main gaps are the unexplained 'account' parameter and a bit more detail on how filters combine, but these are minor given the overall coverage.

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 carries the burden for 13 parameters. It explains from/to as AAAA-MM-DD with a 366-day max, limit/offset defaults and caps, the filter parameters, entry_ids batch semantics, and date_field in depth. However, the 'account' parameter is not mentioned, and some filter parameters like dre_indicator and destination_id get only passing mention without more semantic detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Lê os lançamentos financeiros do iClips'. It enumerates the scope (entradas, saídas, em aberto) and distinguishes the 'get' action as returning full detail by entry_ids. This clearly separates it from the sibling 'list' tool and from other financial modules.

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 concrete usage guidance: date range constraints, default/max limit, offset pagination, filters, and the important use case for month-due entries using type='A Pagar'/'A Receber' with date_field='entry'. It does not explicitly contrast with the sibling iclips_financial_entries_list, but the get/list action split within the description makes the intended usage reasonably 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?

Despite strong annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: the module is read-only 'por decisão dele', list requires from/to, intervals are capped at 366 days, pagination has defaults/max, batch get reports errors per id, and date_field semantics are explained. It also discloses the returned data fields, which is valuable with no output schema present.

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 front-loaded and organized with action bullets, a date_field explanation, a practical example, return data, and a read-only note. It is longer than strictly necessary because the get action is described inside a list-flattened tool, but every remaining sentence carries useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool with no output schema and zero schema descriptions, this is close to complete: required arguments, filters, pagination, date semantics, return fields, and read-only behavior are all covered. The unresolved ambiguities are the role of 'account' and whether the get action is actually available given the flattened action is list.

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 carries the full parameter burden and does so well: it explains from/to format and interval cap, enumerates filters, gives limit default/max and offset, defines entry_ids for batch get, and clarifies the date_field enum values. The only clear gap is the 'account' string parameter, which is never mentioned, so the parameter guidance is excellent but not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Lê os lançamentos financeiros do iClips' and enumerates the covered entry types (entradas, saídas, A Pagar/A Receber). It also separates list vs. get behaviors, so an agent can distinguish this listing tool from iclips_financial_entries_get and the write-oriented siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance, such as using type='A Pagar' with date_field=entry to see what matures in a month, and explains that payment dates only return already-paid items. However, it presents 'get' as an action inside a tool that is flattened to 'list', and it does not explicitly route the agent to the sibling iclips_financial_entries_get, which creates mild ambiguity.

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 mark it read-only and non-destructive, and the description adds significant behavior: max 366-day range, pagination defaults, batch get with per-id error reporting, and the status/motivo de cancelamento handling. 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 front-loaded with the main purpose, uses compact action labels, and packs useful constraints into a short block. The trailing '[Flattened action: get]' note adds minor noise but does not undermine readability.

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 seven parameters and no output schema, it describes the query modes, parameter constraints, and returned invoice fields in good detail. The main omissions are the meaning of the account parameter and explicit guidance about choosing between this tool and iclips_financial_invoices_list.

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 compensates for most parameters: from/to dates and maximum range, status filtering, limit/offset pagination, and invoice_ids batch semantics. The account parameter is not explained, preventing a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Lê as notas fiscais de serviço (NFS-e) emitidas pela agência no iClips'. It further details the list and get actions, making the tool's role clear. It does not explicitly differentiate from the sibling iclips_financial_invoices_list, so it falls just short of full sibling distinction.

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 concrete usage context: list requires from and to, with date format and limits, while get is for invoice_ids and returns full details. It lacks explicit 'when not to use this tool' or alternative tool names, but the guidance is clear and non-misleading.

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 mark the tool read-only and idempotent; the description adds meaningful constraints: 366-day maximum range, filtering by issue date, pagination defaults, batched get with per-id errors, and the exact fiscal fields returned. This goes well 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 structured and information-dense: purpose, actions, then return data. The only notable waste is the 'get' action detail that duplicates the sibling tool and the cryptic '[Flattened action: list]' note.

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 no output schema and no parameter docs, this description gives enough to call it correctly: date semantics, pagination, status filtering, batch behavior, and returned fields. It falls short on the undocumented account parameter and on clarifying whether invoice_ids/get is actually callable in this flattened list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining most parameters: from/to format and requirement, limit/offset defaults, status filter, and invoice_ids for batch get. It does not explain what 'account' means, and it introduces a requiredness expectation for from/to that the schema does not encode.

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 reads NFS-e invoices and gives a specific list behavior with date-range and pagination details. However, it also documents a 'get' action even though a dedicated sibling iclips_financial_invoices_get exists, and the '[Flattened action: list]' note muddies exactly which action is active.

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 explains when to use the list action (from/to, status, pagination) and describes the get action, so the internal usage pattern is inferable. It never explicitly says to prefer iclips_financial_invoices_get for invoice details and gives no when-not-to-use guidance, leaving the choice between this tool and its sibling partly ambiguous.

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 that the tool returns jobPecaId, explains its significance for subsequent updates, and lists required/optional data fields. However, it does not discuss side effects, failure modes, or permission requirements, and with readOnlyHint=false and no idempotentHint, the agent is left without information about whether repeated calls create duplicates or are safe.

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 well-organized with a clear overview, action breakdown, and bulk support note. It is front-loaded with the core purpose and provides necessary detail without excessive verbosity. The inclusion of update details in an add-specific tool is slightly redundant but useful context, so not penalized heavily.

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 write tool with no output schema and six parameters, the description gives enough to make a basic add call, including required fields and return value. However, missing details like the serialization of 'data', handling of batch variants, and understanding of 'account' mean the definition is not fully complete for all invocation 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?

Schema description coverage is 0%, so the description must explain all parameters. It covers job_id, data (including optional fields), job_piece_id, and bulk fields job_ids/job_piece_ids, but does not explain the format of 'data' (likely a JSON string) nor the purpose of 'account'. This is a partial compensation, leaving some parameters 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 states a specific verb+resource: linking a catalog piece to an existing job (add) or updating an already-linked piece. It explicitly differentiates between add and update actions, and the '[Flattened action: add]' marker makes clear this tool is specifically the add variant, distinguishing it from the sibling iclips_job_pieces_write_update.

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 parameter requirements for add versus update, including which id to use in each case (pecaId vs jobPecaId). It implies when to use add (when linking a new piece) and points to the iclips_pieces tool for catalog ids, though it does not explicitly state 'use update when the piece is already linked' as a direct exclusion.

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?

Beyond the annotations, the description reveals that add returns jobPecaId for later use in update, that update modifies only supplied fields, and that bulk execution is supported via job_ids and job_piece_ids. It does not detail side effects, idempotency, or error behavior, but the annotations already cover the basic safety profile and there is no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The main purpose is front-loaded and the add/update sections are clearly structured with mandatory vs. optional fields. The add section and '[Flattened action: update]' line add some clutter if the tool is update-only, but the description remains organized and reasonably compact.

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 6-parameter mutable tool with no output schema, the description covers the core identifier model and bulk usage, but it omits the update return value, the account parameter, and explicit data serialization. An agent would still have open questions when invoking the tool for the first time.

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 compensates by documenting data.pecaId, optional data fields, job_piece_id semantics, and bulk id parameters. However, the account parameter is never mentioned, and data is not explicitly stated to be a JSON-encoded string, leaving important gaps for an agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool links a catalog piece to an existing job or updates an already-linked piece, and it distinguishes the add and update modes with their required identifiers. The note '[Flattened action: update]' and the presence of a sibling write_add tool slightly muddy whether add is actually active, so it is not a perfect 5.

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 concrete conditions for add vs. update: add requires job_id and data.pecaId, while update requires job_id and job_piece_id, and tells the agent to send only changed fields. However, it never explicitly routes to iclips_job_pieces_write_add for adding or states when not to use this tool, and the add instructions may be irrelevant if the action is flattened to update.

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?

Adds value beyond the destructiveHint annotation by disclosing no-undo behavior and per-id error reporting. The description makes the destructive nature explicit and explains batch semantics, though it does not mention potential cascading effects on related resources.

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 dense sentences with no filler. The action and critical destructive warning are front-loaded, followed by the key batch behavior.

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 simple schema, presence of destructiveHint, and no output schema, the description covers the essential invocation details: what is deleted, that it is irreversible, and how batch deletion behaves. The only notable gap is the unexplained optional 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?

Effectively explains the required job_ids parameter: it accepts multiple ids, works in batch, and reports errors per id. However, schema description coverage is 0% and the optional account parameter is not mentioned in the description, leaving one parameter undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('Exclui jobs (projetos)') and resource scope ('do iClips'), and adds batch-deletion behavior. This clearly differentiates it from sibling tools that create or update jobs.

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 clear context by warning that the operation is destructive and irreversible via the API, and explains that multiple job_ids can be removed in batch. It does not explicitly state when-not-to-use or name alternatives, but no alternate delete-job sibling exists.

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 goes well beyond the minimal annotations, disclosing required fields, optional fields, status-code semantics, return values (jobId, titulo, sigla, status, totalPecas, totalTarefas), ignored fields on update, and bulk support via job_ids. This gives the agent a strong behavioral model of what the tool does and what side effects to expect, especially since readOnlyHint=false and no other safety guidance 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 dense but well-organized with actions, field lists, status codes, and return values; every major section earns its place. It is slightly longer than necessary because it covers both create and update behaviors, and the '[Flattened action: create]' line is a machine-generated artifact rather than natural prose.

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 complexity of the job creation payload and the absence of an output schema, the description is notably complete: required vs optional fields, status codes, nested task input shape, ignored fields, return fields, and bulk support. It is not perfect because it omits 'account', leaves the 'data' string/object representation unclear, and mixes update semantics into a create-flattened tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It richly explains the 'data' payload, statuses, and job_ids, but it fails to explain the 'account' parameter and does not address the apparent type conflict where the schema declares 'data' as a string while the description treats it like an object. This is a meaningful gap for correct invocation.

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 resource ('job (projeto) no iClips') and the primary action 'Cria', with detailed create-field requirements. It loses a point because it also embeds the update action in a tool named *_create and marked '[Flattened action: create]', leaving some ambiguity about which operation this specific tool actually performs.

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 good guidance on when NOT to use this tool for pieces/tasks, explicitly directing the agent to iclips_job_pieces_write and iclips_job_tasks_write. However, it does not explicitly distinguish when to use iclips_jobs_write_create versus the sibling iclips_jobs_write_update, and the embedded 'update' action blurs that boundary.

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?

Beyond the annotations, the description discloses that modeloIds, pecaIds, and tarefasInput are ignored on update, that bulk execution is accepted via job_ids, and what the response contains (jobId, titulo, sigla, status, totalPecas, totalTarefas). There is 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 content is organized and front-loaded with the action, but it includes a full create-action specification in a tool flattened to update; a lot of that create detail is unrelated and adds noise. The status codes and return-field list are useful but make the description longer than necessary.

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 no inline schema descriptions, the description supplies required fields, optional fields, status enum values, return values, ignored fields, and bulk behavior. The only meaningful omissions are the encoding of the data string and the account parameter's role.

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 full parameter burden and does so well: it details the data payload fields, required combinations, status codes, and job_id/job_ids usage. It does not specify that data must be passed as a JSON-encoded string or explain the account parameter, which are minor 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 states a clear action and resource ('Cria ou atualiza um job no iClips') and goes into detailed action semantics. However, it claims both create and update even though the tool is flattened to update and a sibling iclips_jobs_write_create exists, so the tool is not cleanly differentiated from the create sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The update path is explicit about requiring job_id, and it names the correct alternatives for pieces/tasks (iclips_job_pieces_write and iclips_job_tasks_write) plus fields that are ignored in this tool. It stops short of explicitly contrasting this tool with iclips_jobs_write_create for new jobs, so it loses the top score.

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 context beyond annotations: it explains that the tool writes and returns idTarefaJob for later updates, and warns that write field names differ from read field names returned by iclips_projects_extract. This kind of behavioral nuance is not captured by readOnlyHint or destructiveHint.

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 well-organized with action blocks, optionals, return-value notes, and a field-mapping warning. It is compact given the amount of detail, though it is slightly redundant by documenting both create and update in a create-named tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It covers required fields, optional fields, date/priority constraints, the returned ID, and bulk support. Still, it omits how the data payload should actually be serialized for the string data parameter, leaves account unexplained, and does not fully resolve whether update is really available in this tool. With no output schema, response details are also missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description compensates by listing data fields like titulo, descricao, inicioDate, fimDate, prioridade, and ordemExibicao with constraints. However, there is a notable mismatch: the schema types data as a string but the description treats it as an object with fields, and the account parameter is not 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 states it creates or updates a manual task inside an existing iClips job, naming the verb and resource clearly. However, it covers both create and update actions while the tool name and 'Flattened action: create' signal create-only, creating some ambiguity with sibling iclips_job_tasks_write_update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit requirements for each action: create requires job_id and data.titulo, update requires task_id, and optional fields are listed. It does not mention the sibling alternative or specify when to prefer this tool over iclips_job_tasks_write_update, but the per-action guidance is concrete and actionable.

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 establish readOnlyHint=false, so the write nature is expected. The description adds meaningful behavioral detail: create returns idTarefaJob, update is partial (only send changed fields), and write field names differ from read field names. It does not disclose serialization expectations or error/overwrite behavior, but this is still solid coverage 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 front-loaded with a clear purpose and organized into create/update actions, making it easy to scan. The field-name mapping note and bulk support sentence are valuable. The cryptic line '[Flattened action: update]' adds confusion and prevents a perfect score.

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 required and optional fields, the returned idTarefaJob, bulk support, and the read/write naming mismatch, which is substantial for a write tool. It is not fully complete because there is no output schema and the description does not clarify how the string-typed data parameter should be encoded or how bulk task_ids/job_ids interact with data. These are important gaps for reliable 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?

With 0% schema description coverage, the description carries most of the parameter burden. It explains job_id, task_id, data subfields, and the bulk job_ids/task_ids. However, it treats data as an object via data.titulo while the input schema types data as a string, leaving the required serialization format ambiguous. The account parameter and how data behaves in bulk batch calls are also 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 clearly states the verb and resource: it creates or updates a manual task inside an existing iClips job. It also differentiates from read tools by warning about different field names. However, it loses a point because the tool name and '[Flattened action: update]' suggest an update-only tool, while the description also claims create behavior, and it does not explicitly distinguish itself from the sibling iclips_job_tasks_write_create.

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 explicit conditions for create versus update: create requires job_id and data.titulo, while update requires job_id and task_id, and only changed fields should be sent. It also provides a useful routing hint about field-name differences from iclips_projects_extract. It stops short of 5 because it never explicitly says when not to use this tool or names the sibling create tool as an alternative.

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. The description adds useful context about the scope ('ligadas a este install') and the returned fields, but it does not disclose any additional behavioral details such as authentication needs, pagination, or filtering effects beyond what the annotations imply.

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, efficient sentence that leads with the action and resource, then lists the output fields. Every word earns its place, and there is no redundancy or padding.

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 listing tool, the description covers the resource, scope, and returned fields, and the annotations cover safety. However, it is incomplete for fully correct invocation because it does not explain the optional 'account' parameter, and with no output schema the agent only gets a partial view of the expected response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention the optional 'account' parameter at all. The agent is left with no explanation of what 'account' means, whether it filters the list, or how it should be formatted. This is a significant gap because the description was the only opportunity to clarify the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Lista') and a clear resource: the iClips agencies/API keys linked to the current install. It also names the output fields (id, apelido, nome), which distinguishes it from sibling tools like iclips_financial_accounts.

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 no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or comparison with sibling tools such as iclips_financial_accounts, leaving the agent to infer the use case from the name and scope.

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 and idempotentHint, so the description carries less burden. It adds useful detail about the output containing id and name and about dropdown being a simplified selection-friendly format, but it does not add deeper behavioral context such as authentication 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 compact, front-loaded with the main purpose, and easy to scan. The '[Flattened action: dropdown]' line is internal tooling metadata that adds minor noise, but the overall structure is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only lookup with one optional parameter, the description covers the output shape and downstream usage well. The remaining gaps are the meaning of the account parameter and the lack of an explicit comparison with iclips_piece_categories_list.

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 one undocumented string parameter, account, with 0% schema description coverage, so the description must compensate. It mentions 'na agência' but never explains that the account parameter selects the agency or how it affects the returned categories.

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 verb and resource: it lists piece categories available in the agency, returning id and name. It also distinguishes the dropdown flavor from the full list by explicitly saying the dropdown action returns the same categories in the simplified format iClips uses for selection fields.

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 clear usage context by explaining that the returned ids should be used in categoriaIds when creating or updating a piece. It does not explicitly name the sibling list tool or state when not to use it, but the simplified dropdown format is clearly tied to selection-field use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context: the data is scoped to the agency, returns id and name, and can be returned in a simplified dropdown format. 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 short and front-loaded, but the 'Actions: list' bullet is largely redundant with the tool name and the first sentence. The dropdown action adds useful information but also blurs the tool's scope. Overall it is compact yet could be tighter.

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 list tool this covers the return shape and the purpose of the ids. But it leaves the optional account parameter undocumented and never points to the dedicated sibling dropdown tool, which is a notable gap for a complete call specification.

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% and the only parameter, account, is a bare string. The description never mentions account or how it affects the result, so an agent has no way to know whether to supply it or what values are valid.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource: it lists piece categories available in the agency, returning id and name. It also states the downstream purpose of the ids. However, it includes a 'dropdown' action and does not explicitly distinguish this list tool from the sibling iclips_piece_categories_dropdown, so it is not a perfect 5.

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 explicit downstream guidance ('use these ids in categoriaIds when creating or updating a piece'), which tells an agent why to call it. It does not, however, explain when to use this tool vs the sibling dropdown tool or when not to use it, so the usage guidance is implied rather than fully specified.

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 annotations by disclosing that the provider performs logical deletion and that errors are reported per id. This complements the destructiveHint=true annotation without contradicting it.

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 succinct sentences front-load the core action and follow with the key batch and error-reporting behavior. There is no filler 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 destructive tool with no output schema, the description covers the key call context: logical deletion, multi-id batching, and per-id error reporting. The undocumented 'account' parameter is a minor gap but does not undermine overall usability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains that piece_ids enables batch deletion and per-id error reporting, which adds value beyond the bare schema. However, with 0% schema coverage, the optional 'account' parameter is left completely undocumented, so compensation is only partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool deletes pieces from the iClips catalog, a specific verb and resource. The logical deletion note adds a meaningful scope distinction, and the delete operation is clearly differentiated from sibling get/list/write tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: to delete pieces, including multiple at once via piece_ids. However, it does not explicitly mention alternatives or when not to use it, leaving some routing to inference.

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 readOnly/idempotent/non-destructive behavior; the description adds concrete behavioral detail: batch get by piece_ids, complete workflowJson/checklistJson payloads, per-id error reporting, and a default page size of 20. 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 one-line summary and action bullets are compact and front-loaded, with no filler. The 'Flattened action: get' line and the list action add some redundancy/ambiguity, but the structure is easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter read tool with no output schema and no parameter descriptions, it supplies most invocation details (filters, pagination, batch get, returned fields). It remains incomplete around the 'account' parameter, exact response/error shapes, and how the list action relates to iclips_pieces_list.

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 compensates well by explaining q, categoria, status, basedOnTemplateId, page, pageSize (default 20), and piece_ids. The only schema parameter left unexplained is 'account', and the description does not state optionality/requiredness beyond q being optional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Lê o catálogo de peças da agência no iClips') and outlines two read actions, so an agent can infer this is a read-only piece-catalog tool. However, it does not differentiate from the sibling iclips_pieces_list, and including a 'list' action in a tool named 'get' blurs the distinction.

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 usage context for parameters (list with q/filters/pagination, get with piece_ids) and implies that get is for full workflowJson/checklistJson details. It never states when to choose this tool over iclips_pieces_list or when not to use it, and the included list action competes with that sibling.

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 goes well beyond the annotations by disclosing pagination defaults (pageSize 20), supported filters, batch retrieval behavior, and per-id error reporting for the get action. The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description does not contradict 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 compact, front-loaded with the overall purpose, and uses clear bullets for the two actions. The trailing '[Flattened action: list]' marker adds minor noise but does not undermine readability.

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 operation modes, common filters, pagination, and the special payloads returned by get. However, there is no output schema, no return-shape description, and no explanation of the account parameter, so an agent still has notable gaps when invoking 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?

With 0% schema description coverage, the description must compensate for missing parameter meaning. It explains q, categoria, status, basedOnTemplateId, page, pageSize, and piece_ids, but it omits account entirely, and it gives no format or allowed-value guidance for status or basedOnTemplateId.

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 reads the agency's piece catalog on iClips and enumerates two specific actions: list and get. It is a specific verb + resource, but it does not differentiate itself from the sibling iclips_pieces_get, which creates some ambiguity about why both exist.

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 internal usage context: use list for optional text search with filters and pagination, use get for detailed piece data including workflowJson and checklistJson in batch. It stops short of explicitly saying when not to use this tool or naming alternatives such as iclips_pieces_get.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description exposes a critical behavioral trap: for update, it states the endpoint SUBSTITUI both workflowJson and checklistJson and advises reading the piece first. It also explains that create returns the new piece id, that checklist toggles done/pending, and that bulk execution is supported via piece_ids. These are non-obvious side effects and execution details that an agent needs.

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 action-by-action structure is organized and the update replacement warning is front-loaded within the update bullet. But the description is longer than necessary for a checklist-flattened tool, and the extensive create/update details are likely extraneous given the tool name and '[Flattened action: checklist]' signal.

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 checklist action, the core requirements are present: piece_id, data {itemId, done}, and bulk support. Yet the description doesn't explain how bulk piece_ids interact with data, what the response looks like (no output schema exists), or how to encode data as a string. The mixed create/update/checklist coverage further reduces confidence in whether this tool can be invoked safely without extra 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?

With 0% schema description coverage, the description compensates substantially by detailing what goes inside data for each action, including required fields, the exact-one-of constraint between basedOnTemplateId and workflowJson, optional fields, and the {itemId, done} shape for checklist. However, it does not clarify that data is a string in the schema, nor what the account parameter means, and bulk semantics are only vaguely stated.

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 names a clear resource and multiple actions ('Cria ou atualiza uma peça no catálogo do iClips, ou marca um item do checklist'), but it is ambiguous which actions actually apply to this tool. The name 'write_checklist' and the line '[Flattened action: checklist]' suggest only the checklist action is available, yet the description documents create/update in full, blurring the distinction from sibling tools like iclips_pieces_write_create and iclips_pieces_write_update.

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?

There is useful prerequisite guidance ('Use iclips_workflow_templates para descobrir o basedOnTemplateId' and 'leia a peça antes com iclips_pieces action=get'), but the description never says when to choose this tool over the existing write_create/write_update siblings. It even documents create/update behavior as if those actions are available here, so an agent could be misled into using this tool for tasks that belong 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?

Beyond the annotations, the description discloses that create returns the new piece id in data and that bulk execution accepts piece_ids. It also transparently warns that update replaces workflowJson and checklistJson, though that behavior belongs to a sibling tool. No statement contradicts 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 message is long and includes full update and checklist workflows that are irrelevant for a create-flattened tool, making it harder for an agent to extract the create-specific contract. The create details are front-loaded and organized, but the extra action modes should have been removed or replaced with pointers to sibling tools.

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 write operation with no output schema and high parameter complexity, the description covers most of what an agent needs to call create correctly: required data fields, optional fields, return id, and where to find category/template IDs. It falls short on payload serialization, bulk semantics, and account parameter, and the embedded update/checklist text muddies the create scope.

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 does substantial work by enumerating required and optional fields inside data, the 255-character name limit, the exactly-one constraint, and categoriaIds as int[]. However, it does not explain that data is a string that must contain a serialized JSON payload, nor does it define account, piece_id, or piece_ids beyond a terse bulk note.

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 create action is clearly described: it creates a piece in the iClips catalog, requires name plus exactly one of basedOnTemplateId or workflowJson, and returns the new piece id in data. However, the opening sentence and action list also claim the tool updates pieces and marks checklist items, which are covered by sibling tools, so the purpose is not sharply differentiated for this create-specific variant.

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 strong operational guidance for the create path, including required data fields, the exactly-one constraint, and optional fields. It also points to iclips_workflow_templates and iclips_piece_categories for discovering valid IDs. It never states when-not-to-use this tool or routes update/checklist actions to their sibling tools; instead it documents those actions inline, which could mislead an agent.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses a key behavioral trait: update SUBSTITUI workflowJson and checklistJson, so the agent must read the piece first. It also mentions bulk support via piece_ids. No contradiction with annotations, and the destructive replacement semantic is useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized by action, with the main purpose front-loaded and each sentence adding constraint or routing information. The bulk-support note and flattened-action marker are useful. It could be slightly cleaner by explaining the flattened-action notation, but overall it earns its length.

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 complexity (three actions, 4 parameters, no output schema), the description covers most operational semantics and prerequisites. But it does not describe return values for update/checklist actions, leaves 'account' undocumented, and does not state how this tool relates to the dedicated create/checklist siblings. These gaps make it incomplete enough that an agent may still need to probe or guess.

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 carries the full burden. It compensates well by explaining the data field's internal structure, required vs optional fields, field constraints (name ≤ 255 chars, exactly one of basedOnTemplateId/workflowJson), and the meaning of piece_id and piece_ids. However, the 'account' parameter is never mentioned, and the description does not clarify that 'data' is a string in the schema while treating it as an object.

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/updates an iClips piece or marks a checklist item, with explicit resources and verbs. However, it does not differentiate this tool from the sibling tools iclips_pieces_write_create and iclips_pieces_write_checklist, and the '[Flattened action: update]' note adds ambiguity about whether all three actions are actually available here.

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 per-action requirements: create needs name plus exactly one of basedOnTemplateId/workflowJson; update requires piece_id and read-before-write because workflowJson/checklistJson are replaced; checklist requires piece_id and itemId/done. It also points to supporting tools for templates and categories. It stops short of explicitly stating when to use this tool instead of the create/checklist siblings, so it does not fully earn a 5.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context: the 10-request-per-minute rate limit, the 31-day maximum interval, filtering by job entry date, and the need to paginate using meta.totalCount. This goes well beyond the structured metadata and gives actionable guidance for avoiding failures.

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 dense but every sentence earns its place: core capability, unique value, required parameters, optional filters, pagination, and rate-limit warning. No fluff or repetition of the tool name 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?

There is no output schema, but the description covers the returned subject matter (hierarchy down to time entries, department, hourly value) and mentions meta.totalCount for pagination. The missing explanation of the 'account' parameter and the lack of any output-shape details prevent a perfect score, but overall it is quite complete for a complex extraction endpoint.

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 almost the entire burden, and it handles this well: dataInicio/dataFim are explained with format and interval constraints, idCliente/idGrupoCliente are identified as optional filters, and page/pageSize get defaults and maximums. However, the 'account' parameter is completely unexplained, leaving one of the seven parameters without any semantic guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb and resource: extracting the complete project hierarchy from iClips, explicitly listing Jobs, Peças, Workflows, Atividades, Tarefas, and time entries. It clearly separates itself from siblings by positioning itself as the BI/export/report endpoint and stating it answers what other tools do not.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: for BI, export, and reporting across a project hierarchy, especially cross-cutting questions about hours worked per piece/job/client. It provides operational constraints (required date range, max 31 days, optional client filters, pagination) but does not explicitly name sibling alternatives or state when not to use it.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond that: list omits workflowJson, get returns the complete workflowJson for multiple ids in batch, and errors are reported per id. This gives the agent a clear operational model of the tool's 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 compact, front-loaded with the core purpose, and uses bullets to distinguish list and get behavior. The integration note is short and actionable. Every sentence contributes meaningful information without unnecessary 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 simple two-parameter read tool with no output schema, the description covers the key return surface (fields per mode, workflowJson presence, batch error reporting) and the downstream use case. It is missing an explicit explanation of account and a direct comparison with the sibling list tool, but otherwise it is adequately 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?

Schema description coverage is 0%, so the description must compensate. It explains that template_ids selects one or more templates and that the returned id is used as basedOnTemplateId. However, the account parameter is never explicitly described beyond the vague 'agência' context, and requiredness/missing-value behavior is not addressed.

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 operation — reading iClips workflow templates — and clearly distinguishes the 'list' mode (id/name/description only) from the 'get' mode (full workflowJson, batched). It does not explicitly name the sibling iclips_workflow_templates_list as the alternative, so a small differentiation gap remains.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the 'get' action (full workflowJson) versus the lighter 'list' action, and it tells the agent that returned ids feed basedOnTemplateId in iclips_pieces_write. It does not explicitly state when NOT to use this tool or mention sibling alternatives, but the action-level guidance is sufficient for most selection decisions.

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 detail beyond the readOnlyHint and idempotentHint annotations: list returns only id, name, and description without workflowJson, while get returns full workflowJson in batch with per-id error reporting. This is valuable operational context for an agent.

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 well-structured with a short lead sentence, bulleted actions, and a cross-reference to iclips_pieces_write. The trailing '[Flattened action: list]' marker is somewhat confusing and not clearly useful to the agent, but the overall size is appropriate.

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 description does a good job of explaining list vs get return contents and how to use the resulting id. It is still missing an explanation of the account parameter and how the get action is triggered explicitly, but the core invocation paths are understandable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains that template_ids triggers the get action and returns the full workflowJson, which compensates for the 0% schema coverage on that parameter. However, the account parameter is not explained at all, so parameter semantics are only partially covered.

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 reads iClips workflow templates and distinguishes list vs get behavior. However, it does not explicitly differentiate itself from the sibling iclips_workflow_templates_get, and the inclusion of a get action inside a list-named tool adds mild 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?

It gives clear context for when to use the list action vs the get action via template_ids, and it tells the agent to use the returned id as basedOnTemplateId when creating a piece. It does not mention the sibling get tool or state when not to use this tool, so it falls short of explicit alternative routing.

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?

Beyond the annotations, the description discloses important behaviors: invoke runs an MCP even when it is not installed, does a one-off run without adding the MCP to the toolkit, returns a connect link when credentials are needed, returns a checkout/top-up link when payment is needed, and requires workspace owner/admin for write operations. The description enriches the annotations and does not contradict 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 front-loaded with identity and the core flow, and nearly every sentence carries useful guidance. However, it is one dense, wall-of-text paragraph with mixed language ("pontualmente") and heavy inline emphasis, which makes the many action alternatives hard to scan and 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?

For a complex 23-parameter, 14-action facade with no output schema, the description is remarkably complete: it covers the core flow, one-off invoke semantics, auth/credential/payment behavior, permission requirements, installed flags, the prompt library, and most action outcomes. The main gaps are the resume action and return-shape details for a few actions, but the overall guidance is sufficient for correct invocation in most cases.

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 does a lot of compensating work: it maps action values such as search, describe, invoke, install, list_tools, publish_prompt, and explains tool_id, arguments, and prompt-related intent. However, several parameters and enum actions remain unexplained, including resume, limit, immediate, tier_slug, cancel_reason, report_context, conversation, request_name, and request_details, leaving agents under-specified for those paths.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as the official mcp.ai marketplace: the in-platform catalog of MCPs/tools and the way to run them. It states the core discovery→describe→invoke flow, distinguishes the prompt-library subdomain from the MCP flow, and makes it clear this is a marketplace orchestrator rather than one of the sibling calculator/authenticate tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: use install only to make an MCP permanent, prefer invoke for one-off use, use list_tools to see what is callable now, use subscribe/cancel for billing, and use request_mcp when nothing fits. It also explains what to do when invoke returns a connect link or checkout link, including retry behavior.

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 carry the safety profile with idempotentHint=true and destructiveHint=false. The description adds that conversation data is needed for reproduction, which is useful context. However, it does not disclose what happens after submission, such as whether a ticket is created or whether the report is asynchronous, though the annotations lower the burden.

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 consists of two tight sentences: the first states the purpose, the second gives the key usage instruction. There is no filler, repetition, or irrelevant 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 simple three-parameter reporting tool with annotations already covering idempotency and destructiveness, the description is mostly sufficient. The main gaps are the unexplained `context` parameter and the absence of any indication of what the response or outcome will be, though no output schema is expected.

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 undocumented parameters. It only clarifies the `conversation` parameter via 'conversation array with recent messages,' leaving the required `message` and optional `context` undefined. The agent must guess at their intended content.

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 the verb 'Report' and explicitly enumerates three targets: 'bug, missing feature, or send feedback'. This makes the tool's purpose unmistakable and easily distinguishable from the sibling calculo_* and authentication tools, which serve entirely different functions.

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 establishes a clear context: use when a user reports a problem or wants to provide feedback. It also adds practical guidance to 'Include the conversation array with recent messages for reproduction.' It does not name alternatives, but none of the sibling tools overlap with bug reporting, so exclusions are unnecessary.

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=true and idempotentHint=true, so the agent knows this is a safe, non-mutating call. The description adds little beyond that—it names the output as versions but doesn't specify the format (e.g., semver strings, JSON object) or whether the output is human-readable. Since the annotations carry the safety profile, 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 sentence of 9 words, front-loading the action ('Show') and the object ('version'). There is zero waste, and it fully conveys the tool's purpose within its scope. This is a model of 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?

For a zero-parameter, read-only, idempotent tool with no output schema, the description is nearly complete. An agent can confidently invoke it without additional context. The only minor gap is that the return format is unspecified, but since there is no output schema, a brief note on the output structure (e.g., 'returns a plain-text summary') would elevate completeness. Still, the description is sufficient for correct 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?

The tool has zero parameters, and the schema coverage is 100% (no properties). The description doesn't need to explain parameters. The baseline for zero-parameter tools is 4, and the description is consistent with that—it correctly implies that no input is required.

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: 'Show the current MCP platform and adapter versions.' This is a specific verb-resource pair that distinguishes it from sibling tools, which are all calculation or authentication tools. It could be slightly more explicit about what 'show' returns (e.g., a text summary vs. structured data), but the resource is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies that this tool is for checking version information, which makes sense in contexts where an agent needs to confirm platform/adapter versions before proceeding. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention whether version information is needed for authentication or compatibility checks. Given the sibling tools are all calculations, the usage context is reasonably clear, but not explicitly delineated.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by detailing what kind of state is returned, including connection status and account bindings, which helps the agent understand the tool's informational scope.

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 tightly packed sentence with the main action front-loaded, followed by a colon-delimited list of return contents. Every phrase earns its place with no repetition or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only introspection tool, the description fully covers what the agent needs to know before calling: what information it will receive. No output schema exists, but the description essentially provides a light output contract by enumerating the returned components.

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 is empty with zero parameters, and schema description coverage is 100%, so the description has no parameter burden. Per calibration, zero-parameter tools receive a baseline of 4; the description's output-focused content is more than sufficient.

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 ('Returns') and resource ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific enough to distinguish it from computational siblings like calculo_* and action tools like authenticate or connect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly conveys that this is the tool to call when an agent needs an overview or snapshot of the toolkit's current state. It does not explicitly list exclusion criteria or name alternatives such as show_version, but the context is clear enough for routine selection.

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