iClips

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

Annotations already indicate idempotent and non-destructive behavior, and the description adds useful context: login happens in the browser, configured tokens are non-expiring, pasted tokens are session-only, and calling with no args returns a link. It does not specify return values, but this is minor given the simple workflow.

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

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

The description is compact and front-loaded with the core action and best practice. The 'MCP.AI for IDE agents' opener is mildly extraneous, but every subsequent sentence contributes meaningful usage 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 tool with one optional parameter and no output schema, this description covers all relevant invocation modes and the permanent versus session-only distinction. It could go further on expected response/error behavior, but the essential context for an agent to help a user authenticate is present.

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

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

The schema only declares an optional string 'token' with no description, so the description must compensate. It does so by explaining that token is a JWT to be pasted, that omitting it returns a login link, and that using a configured header is the recommended permanent path.

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 action (authenticate/log in), the resource (access token for the MCP server), and the browser-based flow. It is specific enough to distinguish itself from the domain-specific sibling tools, as it is the only tool concerned with authentication and token exchange.

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 guidance on when to use the permanent config-header approach versus the session-only pasted-token approach. It also clearly states when to call with a token and when to call with no arguments to get a login link.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description needs less behavioral disclosure. It adds meaningful conditional details: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. No contradiction with annotations.

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

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

Two sentences convey the action and both important conditional outcomes without filler. The main behavior is front-loaded, and each clause 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 parameterless status tool with no output schema, the description covers the all-connected and missing-credential cases well. It could more explicitly address partial-connection states, but nothing blocks an agent from calling 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?

The tool has zero parameters, so the schema carries no input burden and the baseline is 4. The description appropriately spends its effort on output states rather than parameter meaning.

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 'Returns connection status and URLs,' giving a specific verb and resource. It then clarifies the two key output states, fully connected versus missing credentials, which distinguishes it from the sibling `authenticate` action.

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

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

The description provides clear usage context: call it to check connection status and obtain connect URLs when providers are missing. However, it does not explicitly mention alternatives or say when not to use it, such as when the agent should call `authenticate` instead.

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?

With annotations only saying readOnlyHint=false, the description carries the side-effect burden and meets it well: invoke runs one-off without installing, install/uninstall/subscribe/cancel plus the one-off install behind invoke require owner/admin, paid/credential-required cases return links instead of failing, and publish_prompt returns a login-free shareable link. No statement contradicts the annotations; it enriches the openWorldHint with concrete external effects.

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

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

The description is dense and logically ordered: catalog definition, core flow, key one-off behavior, credential/payment outcomes, install-vs-invoke guidance, action catalog, auth note, and prompt library section. Minor redundancies ('without adding the MCP to the toolkit and without bloating the tool list') and the untranslated word 'pontualmente' keep it from perfect concision.

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

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

For a 23-parameter, 14-action tool with no output schema, the description covers the main workflow, return behavior for describe/invoke/publish_prompt, auth requirements, and billing edge cases. It misses the `resume` action entirely and leaves `immediate` and `tier_slug` unexplained, which are visible gaps in an otherwise comprehensive picture.

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 compensates by explaining the critical `action` enum values and tying `mcp_id`, `tool_id`, and `arguments` into the search→describe→invoke flow. It also gives meaning to the prompt-related params through the prompt library section. However, several params remain unmapped (`immediate`, `tier_slug`, `conversation`, `request_*`, `cancel_*`), so the compensation is incomplete.

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 the resource (mcp.ai marketplace), its dual function (catalog and execution), and enumerates every major action category: search, describe, invoke, install, list_tools, subscribe/cancel, report_bug, request_mcp, and prompt-library functions. It even contrasts list_tools ('what is callable right now') and request_mcp ('build a NEW MCP') to avoid ambiguity with siblings. This is a specific, multi-verb but unambiguous purpose statement.

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 decision rules: use invoke for single/occasional use, install only for permanent toolkit membership, subscribe/cancel for per-MCP billing, and request_mcp when nothing fits. It also explains the retry flow for credential and payment links returned by invoke. The only minor omission is the `resume` action, which is never mentioned.

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

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

Annotations already disclose idempotence and non-destructive behavior, lowering the bar for the description. The description adds that conversation messages should be attached for reproduction, but it does not explain what happens on submission, whether authenticated user context is included, or what response the caller should 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?

Two short sentences deliver the purpose first and then the one non-obvious usage requirement. There is no filler or redundant restatement of the tool name.

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

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

This is adequate for a simple reporting tool: the agent knows why to call it and roughly what to include, and only one parameter is required. The main gaps are the undocumented 'context' parameter, the array-vs-string wording for 'conversation', and no indication of the return value, though annotations cover the safety profile.

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, and it partially does: it explains that 'conversation' should contain recent messages for reproduction and implies that 'message' carries the report content. However, the 'context' parameter is never explained, and calling the value a 'conversation array' is slightly at odds with the schema type 'string'.

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 an unambiguous verb and resource: it reports bugs, missing features, or feedback, which clearly separates it from the unrelated iclips/financial sibling tools. It does not explicitly contrast with a sibling, but no sibling overlaps with this function.

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 usage context: use this tool when you need to report a bug, request a missing feature, or send feedback, and include conversation history for reproduction. It does not discuss exclusions or alternative tool routing, but the intended use is obvious.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile thoroughly. The description adds the scope of what is shown (platform and adapter versions) but discloses little else, such as output format or whether a live connection is queried. 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?

A single 10-word sentence that front-loads the verb and resource with zero wasted words. Every element earns its place, and no redundant phrasing is present.

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 rich annotations, the description is complete: it names exactly what the tool reports. No output schema exists, but the return value is self-explanatory for a version query, so nothing an agent needs to call it correctly is 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?

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing the description needs to clarify about parameter semantics, and schema coverage is trivially 100%.

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

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

The description uses a specific verb ('show') and a specific resource ('current MCP platform and adapter versions'), making the tool's function unambiguous. It is clearly distinct from all sibling tools, which concern authentication, financial data, jobs, and other domain operations.

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?

Usage context is implied by the tool's nature — an agent can infer it should be called when version information is needed — but the description offers no explicit when-to-use guidance or exclusions. It also does not differentiate itself from the related sibling 'toolkit_info', leaving the choice between them 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds useful behavioral context by emphasizing that the state is 'current' and detailing what aspects are included, which goes beyond the annotations without contradicting them.

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

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

The description is one front-loaded sentence that states the main purpose first and then lists the specific data facets. There is no redundant or filler wording, so every word earns its place.

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

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

For a zero-parameter, read-only info tool with no output schema, the description fully explains what the agent will learn: installed MCPs, their connection status, connected accounts, and catalog tool counts. Nothing essential is missing 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 an empty input schema, so there are no parameter semantics to document. Per the rubric, zero parameters warrants a baseline of 4, and the description adds relevant context about what the call reports.

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 a status/inspection operation: it 'Returns the current toolkit state' and enumerates the concrete contents (installed MCPs, connection status, connected accounts, catalog tool counts). This distinguishes it from sibling tools like authenticate, connect, and show_version.

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

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

The description implies the tool is for inspecting toolkit state, but it does not explicitly state when to use it over alternatives or mention any conditions where a different tool should be chosen. It is clear enough contextually but lacks explicit when/when-not guidance.

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