secondbrain

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuine behavioral context beyond them: idempotent semantics ('Si ya existe, la deja como está y la devuelve') and that the existing record is returned. It does not state permissions or full return shape, so not a 5.

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?

Front-loads the core purpose, then idempotency, then the alternative, then the type glossary. The bulleted type list is long but earns its place since the schema enum names alone are unexplained. Slightly verbose but no wasted flourishes.

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 4-parameter mutation tool with an output-less schema, the description covers purpose, idempotency, sibling routing, and enum semantics, which is close to complete. Minor gaps remain around permission requirements and what exactly 'la devuelve' returns, but nothing critical 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?

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks by explaining each relation_type enum value (hierarchy, holding, org, area, subarea, team, client, partner) with example semantics. This meaningfully enriches the otherwise opaque enum.

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 verb+resource ('Crea una relación entre dos entidades del Atlas') and explicitly distinguishes itself from the sibling change_entity_relation_type for the type-changing case. An agent can tell it apart without opening any schema.

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?

Gives an explicit alternative and condition: if the relation already exists it is left unchanged, and to change its type use change_entity_relation_type. It lacks general when-to-use/when-not context (e.g. prerequisites that both entities must exist), so it falls just short of 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 declare this is a non-read, non-destructive mutation. The description adds genuinely useful behavioral context beyond that: the comment is attributed to the token's user, and it is visible to anyone who can open the task, including users via a borrowed board. This visibility/attribution detail is not in the annotations or schema.

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 tight sentences, front-loaded with the action and then the key behavioral facts. No filler or redundancy.

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

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

For a simple append-style mutation with fully documented parameters and no output schema requirement, the description covers what an agent needs: what it does, who it is attributed to, and who can see it. Only minor gaps (e.g., edit/delete semantics of the comment) remain.

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 100%, with clear descriptions for cuerpo, task_id, and workspace_id (including the 'omit if token has fixed workspace' hint). The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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 verb and resource ("Escribe un comentario en una tarea") that is unambiguous and clearly distinct from the read sibling get_task_comments. An agent knows exactly what the tool creates without opening the schema.

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 tool's purpose implies when to reach for it (adding commentary to a task), but there is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. Usage is only implied by the verb.

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

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

Annotations already cover the safety profile (non-read-only, non-destructive, closed-world). Beyond that, the description discloses the actual write mechanic: HTML is inserted immediately before `</body>`, and appended at the end when no `</body>` exists. That is real behavioral context an agent could not infer. It does not discuss permissions, version conflicts beyond the schema-documented base_version, or response shape.

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

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

Three short paragraphs, front-loaded with the core action and followed by the formatting constraint and the alternative tools. Minimal waste; the trailing alternatives sentence is load-bearing rather than filler.

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

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

With no output schema, five params fully documented in the schema, and annotations carrying safety, the description covers the remaining burden: what gets written, where it lands, and which sibling to pick instead. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top: it clarifies contenido must be HTML because that is the stored format, and explains where that HTML lands relative to `</body>` — semantics the schema field text alone does not convey.

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 verb (agregar), resource (artefacto) and scope (AL FINAL, sin retipearlo), plus concrete examples of the growth patterns it serves. It explicitly names the two sibling tools it is not: patch_artifact and save_artifact.

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?

Gives explicit routing rules: use patch_artifact to change text that already exists, save_artifact to replace the whole artifact. Also enumerates positive cases (new section, extra row, log entry), so both when-to-use and when-not-to-use are covered.

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 declare it is a non-destructive, non-open-world write. The description adds that it appends at the end and returns the resulting summary, but omits conflict/concurrency behavior (what happens when base_version is stale), permission requirements, and error semantics for a mutation tool.

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 compact sentences, zero filler, with the append-at-end scope front-loaded before the return-value note. Every clause 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?

Annotations carry the safety profile and the description covers the return value (the document summary), so the essentials are present. The remaining gap is the concurrency/conflict story around base_version, which an agent would need to call this correctly in a multi-writer setting.

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 100%, so the schema already documents content, document_id, base_version and workspace_id. The description only echoes that content is markdown and that existing content is not resent; it adds no meaning to base_version (optimistic-locking token) or workspace_id resolution.

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 verb and resource ('Agrega contenido ... al FINAL de un documento') plus the key semantic distinction that existing content need not be resent, which implicitly separates it from update_document/patch_document. It never names the alternative tools explicitly, so an agent must still infer the boundary against append_artifact or patch_document.

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 is only implied: 'sin reenviar lo que ya tiene' hints this is preferred over a full rewrite, but there is no explicit when-to-use/when-not guidance and no mention of append_artifact or patch_document as alternatives in a sibling list full of overlapping document tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that restatement: it does not say whether linking is idempotent, what happens if the association already exists, or whether it requires the entity to pre-exist.

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 short sentence with zero waste and the core action front-loaded. It is arguably too sparse, but there is no filler to penalize.

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 3-parameter link operation with no output schema, the description is minimally adequate. It leaves gaps around return values and duplicate-association behavior that an agent might want when invoking a mutation.

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 100%, so both required IDs and the optional workspace_id are fully documented in the schema, including the 'omit if the token has a fixed workspace' nuance. The description adds no parameter meaning beyond that, which is the expected baseline.

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 verb ('Vincula') and both resources (a knowledge graph entity and a document), so the agent immediately knows this creates a link. It does not explicitly name the inverse sibling dissociate_document_entity, but the action itself is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the dissociate_document_entity alternative for unlinking. The agent must infer the context entirely from the tool name and sibling list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safe-read profile is covered structurally. The description adds real context beyond that: the tool is a one-shot onboarding trigger, it returns guidance instead of re-drawing on subsequent calls (idempotency), and its interaction model is tap-based. It stops short of describing the return payload shape in any detail, keeping it at 4 rather than 5.

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 paragraphs, front-loaded with the purpose before the invocation rule. Nearly every clause earns its place, though the parenthetical 'las instrucciones del servidor lo dicen' is redundant rationale that could be trimmed.

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?

No output schema exists, and the description supplies the key return behavior an agent needs (guidance on where to proceed if already run). For a zero-required-parameter onboarding tool with full schema coverage and clear annotations, this covers what is needed; only the exact return format remains implicit.

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 100% and both parameters (idioma, workspace_id) are already documented in the schema, so the baseline is 3. The description adds nothing about parameter behavior — no mention of language selection, workspace resolution, or the default 'es' behavior — so it neither helps nor harms.

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 verb+resource ('Dibuja la bienvenida de una cuenta NUEVA') and details the artifact it produces: a card with three concrete workspace-setup questions, answered by tapping rather than writing. This is clearly distinguishable from siblings like configurar_workspace, which would be the tool that actually persists settings.

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?

Gives an explicit trigger and ordering constraint: call it ONCE, before anything else, when the Secondbrain is empty, with the rationale that server instructions say so. It also names the when-not condition ('si ya se hizo, devuelve por dónde seguir y no dibuja el formulario'), so the agent knows the outcome of a redundant call.

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 destructiveHint=true, but the description adds crucial context beyond that: it specifies that it deletes the cron row, removes the timestamp from the note, and clears the task notice, while explicitly stating the note text remains. This precisely defines the destructive scope, which is the key behavioral information 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?

Front-loads the action in the first clause and then details side effects. It is efficient, though the first sentence is long and could be broken for readability; still, every clause earns its place.

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

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

Given the destructive mutation with no output schema and full schema coverage, the description covers the key side effects and what remains. It does not cover error handling or reversibility, but annotations already flag destructiveness, so it is nearly 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 100%, so the schema already fully documents reminder_id and workspace_id. The description adds no parameter-specific details, so the baseline 3 is appropriate.

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 verb ('Da de baja') and resource ('un recordatorio') and details exactly what it does: deletes the cron row, removes the timestamp from the note, and clears the task notice. However, it does not explicitly differentiate from sibling tools like update_reminder or get_reminders, so it stops short of a 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?

No guidance on when to use this tool versus alternatives. There are no prerequisites, conditions, or named alternative tools mentioned. The description only explains what the tool does, not when or why to invoke it.

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

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

Annotations already declare this as a destructive, non-read-only mutation. The description adds useful meaning for the relation-type values but does not describe permissions, side effects, reversibility, or error behavior 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 purpose is front-loaded in one sentence, followed by a relevant reference list for the enum values. The list is long but directly useful and contains no wasted 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?

For a focused mutation tool with full schema description coverage and destructive annotations, the definition is largely complete. It could say more about failure conditions or consequences, but it covers the key operation and relation-type meanings.

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 100%, so the schema already documents all parameters. The description adds value by explaining the semantic meaning of each relation_type enum value, which the schema does not do.

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

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

The description states a specific verb and resource: it changes the type of an existing relation between two Atlas entities. The phrase 'que ya existe' also distinguishes it from sibling tools that add or delete relations.

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

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

It clearly implies when to use the tool: to change the relation type of an already existing relation. It does not explicitly name alternatives such as add_entity_relation or delete_entity_relation, but the existing-relation condition provides enough context.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description goes well beyond that by enumerating the actual side effects — registering the close, converting "⏰" reminders into timed tasks, flipping the note to read-only — and by disclosing a non-obvious omission (declared tasks are not materialized here, unlike in-app). It also frames the operation as non-destructive but effectively irreversible except via reopen.

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?

Front-loaded with the core action and the app analogy, then the caveats, then the inverse operation — a logical order with no filler. It is somewhat dense and run-on (em-dash aside plus three tool references in five lines), which costs it the top mark.

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 2-param, no-output-schema mutation tool, the description covers triggers, side effects, the ordering constraint with create_task, and the undo path. It stops short of stating the response shape or what happens if the day is already closed / an invalid date is passed, which are the remaining gaps.

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

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

Schema description coverage is 100% and both parameters (date as YYYY-MM-DD, workspace_id as UUID-or-name) are fully documented in the schema itself. The description adds no format, defaulting, or resolution semantics beyond that, so the baseline 3 applies.

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 verb+resource ("Cierra el día") and immediately anchors it to the analogous in-app button, while naming three siblings by name (get_declared_tasks, create_task, reopen_day_note). An agent can distinguish this from write_daily_note or reopen_day_note without opening any schema.

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

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

Explicit prescriptive guidance: provisional tasks from get_declared_tasks are NOT created here, so "si hacen falta, create_task antes de cerrar", and reopening is routed to reopen_day_note. This is a clear when-to-use / what-to-do-first / alternative-tool statement rather than 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=false and destructiveHint=false, and the description is consistent with a write operation. It adds real value beyond them by naming the exact state transition and the timestamp side effect ('le escribe completed_at'), plus a warning that update_task preserves the stale closing date. It stops short of describing the response or idempotency 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?

Front-loads the action and its side effect in the first sentence, then spends the remaining space entirely on disambiguation that prevents a wrong tool choice. No filler or repetition of the title.

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 two-parameter mutation with full schema coverage, annotations, and no output schema, nothing essential is missing: what changes, when to call it, and which sibling handles the inverse case are all 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?

Schema description coverage is 100%: task_id and workspace_id are both documented in the schema, including the fallback of using the workspace name. The description adds no parameter-level detail, so the baseline 3 applies.

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 concrete verb+resource: marks the task as `completed` and writes `completed_at`. The effect is fully specified so an agent can distinguish it from update_task and rollback_task without opening any schema.

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?

Gives an explicit trigger condition ('cuando la persona confirma que la hizo, no cuando lo parece') and routes to alternatives: rollback_task for un-completing (which also clears the closing date) and update_task, whose drawback is explained. Both when-to-use and when-not-to-use are covered.

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 this is a non-read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds real behavioral context beyond that: the rename only happens if the caller is owner or admin, and it has the side effect of creating a Diary note for today. It stops short of saying what happens on re-invocation or whether an existing workspace name is overwritten.

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 tight paragraphs: the first front-loads what the tool does, the second front-loads the calling condition. Every sentence carries information an agent needs, with no filler or repetition of the title.

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 composite mutation tool with no output schema and five optional parameters, the description covers purpose, trigger condition, and the permission constraint on renaming. It is missing only edge-case behavior (idempotency, what happens when the workspace is already configured, or what the response contains), which keeps it short of a 5.

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 100%, so every parameter is already documented in the schema, and the baseline for that situation is 3. The description loosely maps 'para qué lo usa' to uso and 'qué quiere hacer primero' to foco, but adds no format, enum, or default detail beyond what the schema provides, and says nothing about workspace_id.

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 concrete verb and resource and enumerates the composite effects: renaming the workspace, saving usage and focus, and writing a welcome note in today's Diary. It is immediately distinguishable from siblings like update_workspace or write_daily_note because it is an onboarding bundle triggered by the welcome flow.

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 states explicitly that the welcome card invokes it automatically and that the agent should call it only when the client does not render cards and the person answered in writing. That is an explicit when-to-use plus a when-not-to-use condition, leaving nothing 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?

Goes well beyond readOnlyHint=false by disclosing what the created task inherits (título, fecha, responsable, proyecto, organización), that it is tied to the recap and private to the confirmer, that a meeting time becomes a reminder, and that undo removes the task and re-exposes the actionable. The undo/redo restoration detail clarifies why destructiveHint=false is reasonable. Missing permissions/error behavior keeps it from a 5.

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?

Core purpose is front-loaded in the first sentence, then bullets elaborate accept/undo behavior. Length is justified by the branch semantics, though the bulleted prose is slightly heavier than strictly needed.

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 3-param write with no output schema and safety covered by annotations, the description is thorough about effects and reversibility. It never states what the call returns (e.g., the new task id), which would have been useful in the absence of an output schema.

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 100%, so baseline is 3. The description adds real meaning beyond the schema's terse enum note by spelling out the effect of accept (task birth with inherited fields) and undo (task removal, actionable returns), plus noting accept is the default.

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 verb+resource ('convierte un accionable de un recap en tarea, o deshace esa confirmación') and clarifies that the tool also handles undo, which the name alone does not convey. Distinguishable from siblings like dismiss_meeting_actionable and get_meeting_actionables.

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?

Explicitly names the upstream source for ids ('los ids salen de get_meeting_actionables') and frames this as a write invoked 'cuando la persona lo pide o lo confirma'. It does not, however, contrast against the discard sibling dismiss_meeting_actionable, so the when-not is left implicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the copy runs server-side without the content passing through the model, children are NOT copied, and image references still point at the origin workspace's files.

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 short sentences, front-loaded with the core action and scope before the usage rule and the image caveat. Every sentence carries distinct information, though the image note could arguably be folded in more tightly.

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, the description still conveys what the operation does and its side effects (no children, preserved image pointers, server-side execution). It does not state the response shape or what happens on a name collision in the destination, leaving minor gaps for a mutation 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 100%, so the schema already documents all five parameters including defaults and the 'omitir = raíz' behavior for destino_parent_document_id. The description adds only the aggregate statement that name and content are copied, not per-parameter syntax or format detail, so the baseline of 3 applies.

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 verb and resource (copiar un documento) plus the exact scope: nombre y contenido, sin sus hijos. It also specifies destination flexibility (otro workspace —o al mismo—) and the server-side execution model, which distinguishes it from create_document and move_document among 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?

Gives an explicit when-to-use condition ('cuando el mismo documento tiene que estar en dos workspaces') and a recommended workflow (crear uno y copiarlo en vez de generarlo dos veces). It never names move_document as the contrasting alternative, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond restating that an object is created — no note about name uniqueness, permissions, workspace resolution fallback, or what the call returns.

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 front-loaded sentence with no filler or redundancy. It is efficient, though its brevity borders on under-specification rather than optimal sizing.

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 full schema coverage, annotations, and only three flat parameters, the description is minimally sufficient to invoke the tool. It nonetheless omits what is returned (no output schema exists) and any confirmation the canvas was created in the intended workspace.

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 100%, including a useful explanation of workspace_id accepting a UUID or a user-spoken workspace name. The description itself adds no parameter meaning, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ("Crea un nuevo canvas") and scopes it to the workspace, so an agent can distinguish it from sibling creators like create_document or create_clip. However, it offers no explicit differentiation from those siblings beyond the word "canvas".

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 no when-to-use guidance, no prerequisites, and no mention of alternatives such as create_document or create_clip. The agent must infer entirely from the tool name that this is the right choice for canvas creation.

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 flag destructiveHint=true and openWorldHint=true, and the description usefully adds behavior beyond them: processing is asynchronous with summary/key points appearing 'in a few seconds' and read back via get_clip, and re-clipping the same URL updates rather than duplicates. What it does not clarify is what the destructive hint actually means in practice — e.g. that re-clipping overwrites existing note/title/workspace metadata on the prior clip — nor any auth or rate characteristics for the outbound fetch.

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 tight paragraphs: purpose plus async/idempotency behavior first, then the anti-pattern routing. Front-loaded and free of filler. The parenthetical 'resumen y puntos clave aparecen en unos segundos, vía get_clip' is slightly dense but earns its place by telling the agent results are not returned inline.

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 5-parameter create tool with full schema coverage, annotations for the safety profile, and no output schema, the description covers what an agent needs: what it does, that results arrive later via get_clip, that repeat URLs update instead of duplicating, and where to route non-page text. Remaining gaps (exact destructive semantics) are secondary.

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 100%, so all five parameters (url, note, title, workspace_id, parent_document_id) are already documented in the schema, including the title fallback to the page title. The description adds no parameter-level guidance (e.g. how workspace_id resolution interacts with the URL identity used for de-duplication), so baseline 3 applies.

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 concrete verb and resource (save a web page as a clip) and immediately explains the mechanism: server fetches, cleans, and the AI summarizes, retrievable via get_clip. It also distinguishes itself from the near-miss siblings by name (create_document, Daily line), so an agent can choose without opening other schemas.

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?

Gives both a positive trigger (a URL that is a web page, same as pasting into the app) and an explicit negative trigger (text that isn't a page — notes, quotes) with the correct alternative tools named (create_document, diary line). Nothing is left to inference about when to pick this over siblings.

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 it is a non-readonly, non-destructive write operation. The description adds a useful behavioral detail about using the created deliverable's id to link tasks, but does not disclose return format, idempotency, or permission requirements. With annotations covering safety, this is adequate.

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, front-loaded with the core action followed by a relevant integration tip. No wasted words; every sentence earns its place.

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

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

For a simple create tool with complete parameter descriptions and annotations, the description plus structured data are sufficient. It covers the essential post-creation step, though it could explicitly mention that the created deliverable's id is returned.

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 100%, so the schema fully documents all three parameters. The description adds no meaning beyond the schema for name, status, or workspace_id; baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Crea un entregable' (Creates a deliverable). It does not explicitly differentiate from siblings like update_deliverable or get_deliverables, but the create action is clear.

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

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

It provides a usage hint for linking tasks after creation ('pasá su id en deliverable_id...'), but does not state when to use this tool versus alternatives like update_deliverable. Usage is implied rather than explicitly guided.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=false), yet the description adds real behavioral context: markdown→editor conversion, HTML passthrough, line-as-block semantics, mermaid rendering on open, and the returned resumen contents. This is substantive disclosure beyond structured fields.

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?

Front-loaded with the core action and content semantics, then alternatives and return value. Dense and largely every sentence earns its place, though it is on the longer side and could tighten the mermaid/block detail.

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

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

No output schema exists, but the description explains the return value (resumen with bytes, blocks, tables, ordered titles, sha256) enabling verification without re-reading. Combined with alternative routing and content-format rules, it is complete for calling correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description still adds meaning: content accepts markdown or HTML and how each line maps to blocks, and it reinforces parent_document_id for hierarchy. Useful but partly redundant with 100% coverage.

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

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

States a specific verb+resource ('Crea un nuevo documento en el workspace') and immediately establishes scope with format-conversion behavior. It actively distinguishes itself from siblings like patch_document, append_document, copy_document and start_document_upload.

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?

Explicitly routes the agent: use start_document_upload for existing files or >20KB content, patch_document to change a part, append_document to add at the end, copy_document for the same document in another workspace. Names when-not and the exact alternative for each case.

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

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

Annotations already declare non-destructive/non-readOnly/openWorld=false, so the bar is lower; the description still adds meaningful behavior: provider-side creation, workspace visibility of LOCAL events, and that the response reports the resulting calendar. It omits what "con lo que eso implica" concretely entails (invites/notifications) and any permission requirements.

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?

Front-loaded with the core action, then routing, then defaults; most sentences earn their place. Slightly long and partly restates schema semantics ("Sin hora es un evento de día completo"), but structure is logical.

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 mutation tool with no output schema, it covers destination routing, visibility implications, fallback behavior, and the response payload. Remaining gaps (attendees, errors, duplicates) are minor given the tool has no attendee 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?

Schema description coverage is 89%, so the schema already documents `calendar`, `color`, `start_time`, etc. The description reinforces the all-day-vs-timed default tied to `start_time`, but adds little syntax or format detail beyond the schema — baseline 3 for high coverage.

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

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

States a specific verb and resource ("Crea un evento en el calendario de la persona") and immediately scopes where the event actually lands (synced provider vs local workspace calendar). An agent can distinguish this from create_meeting/update_event on the resource alone.

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?

Gives concrete selection logic: pick the synced calendar named in `calendar`, otherwise the default destination, and fall back to LOCAL only when no synced calendar exists. Solid context, but no explicit when-not guidance or named alternatives (e.g., update_event vs create_event).

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive nature is covered structurally. The description adds nothing beyond that - no mention of permissions, what happens on duplicate names, or whether the creation is reversible - so it contributes no behavioral value.

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

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

It is a single short sentence with no waste and nothing buried, but the brevity reflects under-specification rather than disciplined conciseness. There is no structure to front-load because there is only one clause.

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

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

For a 7-parameter, 3-required creation tool with no output schema, the description says nothing about required fields, the workspace_id fallback behavior ('omit if token has a fixed workspace'), or what a successful call returns. Annotations only cover the safety profile, leaving substantial behavioral gaps.

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

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

Schema description coverage is 86% across 7 parameters, so the schema itself documents date, name, summary, workspace_id, and transcription thoroughly. The description adds no parameter-level detail, so the baseline 3 for high-coverage schemas applies.

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 verb plus resource ('Crea una nueva reunión'), which is marginally clearer than the bare tool name, but it is essentially a natural-language restatement of create_meeting. It offers no differentiation from closely related siblings such as create_event, create_meeting_type, or create_document.

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 no when-to-use guidance, no mention of prerequisites (e.g. a valid meeting_type_id or workspace context), and no routing to alternatives like create_event. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safe profile is covered. The description only adds 'en el workspace' scoping and nothing about side effects, validation, or whether creating a duplicate type is possible; with annotations carrying the safety load, the added value here is thin.

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 front-loaded sentence with zero waste. It is appropriately terse, though so brief that it borders on under-specification.

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 create operation with annotations covering safety and no output schema, the essentials are present. Still, it never explains what a 'meeting type' is or how it relates to update/delete_meeting_type, leaving the agent to rely on the schema alone.

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 67%, and the schema itself notably documents workspace_id in detail (UUID or user-spoken name, omit if token has fixed workspace). The description adds no parameter meaning, so it sits at the baseline for partial coverage rather than compensating.

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 verb and resource ('Crea un nuevo tipo de reunión'), so the agent knows exactly what is created. However, it offers no differentiation from siblings like create_meeting, create_event, or update_meeting_type.

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 no guidance on when to use this tool versus create_meeting or update_meeting_type, nor any prerequisites or exclusions. The agent must infer usage entirely from the name.

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 substantial behavior beyond the annotations (which only say non-readonly, non-destructive, closed-world): remind_time writes three places, the cron only reads the `reminders` table, the daily-note line is the source of truth and deleting it cancels the alert, a past time still creates the task but reports the reminder was not scheduled, and private tasks never sync to ClickUp/Jira. This is exactly the side-effect and edge-case context annotations cannot carry.

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?

Long, but front-loaded and organized into labelled sections (RESPONSABLE, FECHA vs HORA, TRAMO, BACKLOG, PRIVADA, DÓNDE VIVE) so an agent can scan it. A few clauses are discursive (the justification for why storing the hour alone is not enough), though they carry genuine behavioral value rather than 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 20-parameter mutation tool with no output schema, the description covers the failure modes an agent must know (validation of the assignee against the workspace, reminder not scheduled when the time has passed) and even names the response field that reports external sync (`destino_externo`), so nothing essential is left implicit.

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 already 100%, so the baseline would be 3, but the description adds real meaning: the assignee vs people vs owner distinction (owner says delegation but not to whom; the assignee must belong to this workspace or the task gets an invisible owner), and the due_date/remind_time and start_date/end_date/due_date interactions. It also states the one-of constraint among jira_project/clickup_list/solo_en_secondbrain.

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?

Opens with a specific verb+resource ("Crea una tarea en el workspace") and immediately states the resulting initial state (`pending`, `source_type: 'mcp'`). It is clearly distinguishable from siblings like update_task, complete_task, and get_task_destinations, which are either named or implied.

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?

Gives explicit conditional guidance for the trickiest choices: which destination parameter to pass ("Se pasa UNO") and where to look if the destination name is unknown ("get_task_destinations los lista"). It explains when remind_time converts a task into a reminder and when urgency vs due_date applies, but never states the general 'use this instead of update_task/get_tasks' framing.

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 destructiveHint=true, so the safety profile is known. The description adds genuine value beyond that by specifying what is and is not destroyed: the artifact leaves the list, but the files of its versions are untouched. It stops short of stating whether the deletion is recoverable via trash.

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 front-loaded sentence with the destructive verb first and the scope caveat in parentheses. No wasted words; the parenthetical earns its place by preventing a wrong assumption about version files.

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 mutation with no output schema, the description covers what gets destroyed, and annotations cover safety. However, recoverability (the existence of get_trash/restore_from_trash) and any permission prerequisites are not mentioned, leaving a gap an agent might care about before deleting.

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 100%, so artifact_id and workspace_id are fully documented in the schema, including the workspace-name fallback. The description adds no parameter syntax or format detail beyond that, so the baseline 3 applies.

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 verb and resource ('Borra un artefacto del workspace') and the parenthetical clarifies the exact scope of removal. It does not explicitly distinguish itself from the many delete_* siblings (delete_document, delete_clip, delete_canvas), but the artifact-specific scope is unambiguous.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as patch_artifact (soft edit), restore_from_trash, or get_trash. Usage is only implied by the verb 'Borra'.

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 destructiveHint=true, readOnlyHint=false and a closed world, so the safety profile is covered. The description adds real value beyond that: the operation is reversible via restore_from_trash and mirrors in-app behavior, which clarifies that 'destructive' here means trashed, not permanently erased.

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 compact sentence that front-loads the operation and its scope. 'como la app' carries little load but does convey behavior parity, so it is not wasted enough to drop below a 4.

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 soft delete, the description plus annotations plus a fully documented schema cover what an agent needs: what it does, that it is reversible, and where to undo it. No output schema is needed since the return is trivial.

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 100%, with both canvas_id and workspace_id documented in the schema itself, including the workspace name-or-UUID flexibility. The description adds no parameter meaning, so the baseline 3 applies.

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 verb+resource ('Manda un canvas a la papelera'), so an agent can tell it apart from the many sibling delete_* tools by the canvas resource alone. It stops short of explicitly naming those siblings, so it falls just under a 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 mention of 'se recupera con restore_from_trash' points at the recovery path and implies this is a soft delete, which is genuinely useful routing context. However, it never says when to choose this over delete_document/delete_clip or when not to use it, so usage is only implied.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuinely new behavioral context beyond that: the operation is soft/reversible and the recovery tool plus type argument needed to undo it, which an agent cannot infer from 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?

A single front-loaded sentence carrying the action, the recoverability caveat, and the recovery tool. "como la app" is the only near-filler phrase but it conveys behavioral parity, so nothing is wasted.

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, 2-parameter tool with no output schema, the definition covers what the agent most needs: what happens (trash, not purge) and how to reverse it. It could still note side effects on related entities or permissions, but the essentials are 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?

Schema description coverage is 100% and both parameters (clip_id, workspace_id) are fully documented in the schema, including the tip to source clip_id from get_clips. The description adds no parameter-level detail, so the baseline 3 applies.

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 verb and resource ("Manda un clip a la papelera") and pins the target type to clip, which cleanly separates it from the many other delete_* siblings (delete_document, delete_event, delete_task). The added note that the action mirrors the app makes the effect unambiguous.

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

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

The description tells the agent this is a trash operation, not a hard delete, and names the exact recovery path (restore_from_trash with type clip). That is meaningful routing context, though it stops short of stating when-not to use it (e.g., permanent removal or when the clip should instead be updated).

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 declare destructiveHint=true, but the description adds the crucial nuance that this is reversible via restore_from_trash, which materially changes how an agent should reason about the destructive hint. It still does not cover authorization requirements or whether attached files/relations are affected.

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

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

A single sentence, front-loaded with the core action and the recovery path, with zero redundant or decorative text.

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 two-parameter tool with complete schema coverage, a safety-related annotation set, and no output schema, the description supplies what annotations cannot: the soft-delete semantics and recovery route. Minor gaps remain around side effects on related entities, but nothing blocks 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?

Schema description coverage is 100%, so both document_id and workspace_id are already fully documented in the schema. The description adds no parameter-level syntax, format, or edge-case guidance, so the baseline 3 applies.

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 verb and resource ('Manda un documento a la papelera') and immediately qualifies the operation as a soft delete, which distinguishes it from permanent deletion siblings like delete_document_file. Naming restore_from_trash and get_trash lets an agent place it correctly without opening any schema.

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?

Gives clear context: this is the trash action, and recovery is done via restore_from_trash while get_trash enumerates trash contents. It effectively routes the agent to the right follow-up tool, but does not explicitly state when not to use it (e.g., vs. permanent deletion or vs. delete_document_file).

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether the file is permanently deleted or moved to trash, whether it can be recovered, or what permissions are required — all material facts given sibling tools get_trash and restore_from_trash exist.

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 short sentence with zero filler and the action front-loaded. It is appropriately sized, though brevity here comes at the cost of the missing behavioral detail.

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

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

For a destructive, irreversible-looking delete with no output schema, the description omits the essentials an agent needs: whether deletion is permanent or to-trash, and how it differs from delete_document. The structured fields cover the parameters, but the behavioral gap is significant.

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 100%, and the schema already explains file_id and the workspace_id resolution rules in detail. The description adds no additional parameter meaning, so the baseline of 3 applies.

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 verb ('Elimina') and resource ('archivo del workspace'), so the action is unambiguous. However, it does not distinguish this from closely-named siblings such as delete_document, delete_artifact, or delete_clip, so an agent must infer that this targets a file attached to a document rather than a document itself.

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

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

There is no guidance on when to choose this tool over delete_document, delete_artifact, or when to use restore_from_trash instead. No prerequisites or preconditions (e.g., ownership or admin rights) are stated.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing CASCADE semantics — relations and links are removed too — but it says nothing about whether the entity is recoverable, whether it goes to trash, or what permissions are needed.

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 front-loaded sentence with the destructive cascade consequence in parentheses; nothing redundant or padded.

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 mutation tool with no output schema and annotations covering the destructive profile, the description supplies the key missing behavior (cascade deletion). Only reversibility/trash behavior and routing against siblings are absent.

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 100%, including a detailed workspace_id description covering UUID/name and the fixed-token case, so the schema carries the parameter burden. The description adds no parameter-level detail beyond it, which is the expected baseline.

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 verb and resource ('Elimina una entidad del knowledge graph'), which is clear and unambiguous. It does not distinguish itself from nearby siblings such as delete_entity_relation, merge_entities, or restore_from_trash, but the core action is unmistakable.

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

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

There is no guidance on when to delete an entity versus merging (merge_entities), editing (update_entity/upsert_entity), or recovering it (restore_from_trash). Usage is only implied by the tool name; no alternatives or conditions are named.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds that entities are not touched, clarifying the scope of destruction. However, it does not mention reversibility, permissions, or error behavior.

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

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

Two short sentences with no waste; the core action is front-loaded in the first sentence, and the scope clarification follows immediately. It is appropriately sized for a simple deletion tool.

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

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

For a destructive operation, the description covers the action and its scope, and annotations handle the safety profile. However, it lacks usage context (e.g., when to choose this over other relation tools) and any mention of error conditions or irreversibility, leaving gaps for an agent to call it confidently.

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

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

Schema description coverage is 100%, so all three parameters (from_entity_id, to_entity_id, workspace_id) are fully documented in the schema. The description adds no parameter-level syntax or format details, which is the baseline when the schema does the heavy lifting.

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 ('Borra') and resource ('la relación entre dos entidades del Atlas'), and distinguishes itself from delete_entity by noting that entities are not touched ('Las entidades no se tocan'). This allows an agent to differentiate it from sibling tools that add or change relations.

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 offers no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of related tools like get_entity_relations or add_entity_relation. It only states what the tool does, leaving the agent to infer usage.

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 flag destructiveHint=true and readOnly=false, but the description adds genuinely new behavioral context: the call silently does nothing for synced events, which prevents a false-success assumption. It stops short of saying whether deletion is reversible or what happens to linked tasks.

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 with zero filler, and the scoping caveat is placed right after the purpose statement where it has the most effect.

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 two-parameter delete with full schema coverage and no output schema, the definition covers the main trap. Minor gaps remain on irreversibility and interaction with linked tasks, which matter for a destructive operation.

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 100%, so both event_id and workspace_id are already documented, including the workspace-name-or-UUID flexibility. The description adds no parameter-level detail beyond the schema, making the baseline 3 appropriate.

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 concrete verb+resource ('Borra un evento') and immediately qualifies scope as LOCAL. That distinguishes it from the update_event/create_event siblings, though no sibling is named explicitly.

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?

Gives an explicit exclusion rule: synced events are not deleted here, they must be removed in their source calendar. A clear when-not-to-use signal, but it does not point to any alternative tool or describe prerequisites.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the key nuance that this 'destruction' is a recoverable move to trash, and it names the restore tool. That clarifies the reversibility of the operation beyond the raw annotation, which is genuinely valuable.

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 front-loaded sentence with zero waste; the scope (to trash) and recovery mechanism are stated immediately.

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 2-param tool with full schema coverage and annotations covering the safety profile, the description supplies the missing behavioral nuance (soft delete + restore path). Nothing critical is absent, though it could note that items in trash reappear via restore and whether the meeting can still be updated meanwhile.

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 100%, so both meeting_id and workspace_id are already documented. The description adds nothing about parameter formats or ID sourcing, so the baseline 3 is appropriate.

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 verb ('Manda ... a la papelera') and resource (recap/reunión), and clarifies it is a soft-delete rather than permanent removal. It distinguishes the action from the harder deletes by naming the trash/recovery path, though it never explicitly differentiates from the sibling delete_meeting_type.

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?

Implies a trash-based soft delete and points to restore_from_trash as the undo path, which is useful routing. However it gives no explicit when-to-use vs alternatives (e.g. delete_meeting_type, update_meeting) and no prerequisites, leaving usage 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 destructiveHint=true and readOnlyHint=false, so the destructive nature is covered structurally. The description adds nothing beyond that — no mention of cascading effects on existing meetings, irreversibility, or required permissions — leaving behavioral gaps for a genuinely destructive operation.

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 front-loaded sentence with zero filler, no repetition of the title, and no wasted words. It is arguably too terse for a destructive tool, but there is no structural bloat.

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 mutation with no output schema and no annotations covering consequences beyond a boolean hint, the description should state what deletion implies for dependent meetings. One phrase leaves the agent without the context needed to act safely.

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 100%: both meeting_type_id and the optional workspace_id (including the 'omit if token has fixed workspace' hint) are fully documented in the schema. The description adds no parameter detail, so the baseline 3 applies.

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 verb ('Elimina') and resource ('tipo de reunión'), so the core action is unambiguous. However, it offers no differentiation from siblings like delete_meeting or update_meeting_type; the agent must rely on the tool name itself to disambiguate.

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

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

No guidance on when to use this versus alternatives (e.g., delete_meeting vs delete_meeting_type), no prerequisites, and no warning about the consequence for existing meetings that reference the type. Usage context is entirely absent.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description's '(acción irreversible)' reinforces that but adds little beyond what the annotation states, and says nothing about auth requirements or whether related data is affected.

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 front-loaded sentence that names the action and its consequence with zero filler. Nothing is wasted.

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 destructive tool with full schema coverage and annotations carrying the safety profile, the description covers purpose and irreversibility adequately. Only recovery/alternative context is missing, which is minor here.

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 100%, with report_id documented as the 'id' from get_reports and workspace_id covering UUID-or-name resolution. The description adds no parameter detail beyond the schema, so the baseline 3 applies.

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 verb ('Elimina') and resource ('un reporte'), plus scope ('del historial del workspace'), which clearly separates it from read siblings like get_reports/get_report and generation tools like generate_report. An agent can identify the operation without opening the schema.

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

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

No indication of when to prefer this over alternatives or related cleanup paths (e.g., get_trash / restore_from_trash), nor any prerequisite or caution about confirmation. The parenthetical about irreversibility is a behavioral note, not usage 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description reinforces and extends this with the permanence claim ('IRREVERSIBLE', 'para siempre') and the consequence that removed tasks no longer appear in history, which is where reports come from. It does not say whether related artifacts (comments, relations) are cascaded, nor whether any recovery path exists despite a restore_from_trash sibling, so it stops short of a 5.

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 irreversible warning is front-loaded in the first sentence, and the second paragraph spends its length only on misuse prevention. No filler or redundant restatement of the title.

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 two-parameter destructive tool with no output schema, the description covers permanence and the correct routing decisively. The one remaining gap is side effects on dependent data and any restore path, which an agent deciding on a hard delete would benefit from knowing.

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 100%, so both task_id and workspace_id are already documented in the schema, including the workspace-name fallback guidance. The description adds no parameter-level detail, which is the expected baseline when the schema carries the load.

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 verb and resource ('Borra una tarea para siempre') and immediately scopes it against siblings: complete_task for finished tasks and a status:'cancelled' update for dropped ones. An agent can distinguish this from delete_document/delete_event-style siblings and from complete_task without opening any schema.

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?

Explicitly frames this as a rarely-correct choice ('Casi nunca es lo que se quiere') and names the two preferred alternatives with the condition that selects each, plus the narrow case where deletion is right ('sólo para lo que se creó por error'). Nothing is left 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 destructiveHint=true, so the safety profile is partly covered. The description adds real value beyond that: it explains the item leaves the list and won't be re-proposed, and critically that an already-converted task is also deleted – a non-obvious cascading side effect worth disclosing.

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?

Purpose and the two key side effects are front-loaded in the first two sentences, with the app analogy and confirmation note following. Four short sentences carry no obvious filler, though the app-cross analogy is slightly superfluous for an agent.

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 two-parameter tool with no output schema, the description covers what is destroyed, the cascade to tasks, and the confirmation requirement. Nothing essential is missing, though it could state return/confirmation semantics more explicitly.

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 100%, so both parameters (workspace_id, actionable_id) are already fully documented in the schema. The description adds no parameter-level detail (e.g. format, where to obtain the id), so the baseline 3 applies.

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 verb ('Descarta') plus resource ('un accionable de un recap') and clarifies scope ('de un recap'), which separates it from get_meeting_actionables and confirm_meeting_actionable by function. It does not name those siblings explicitly, so it falls short of a 5, but the purpose is unambiguous.

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

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

It gives implied usage context ('Es lo mismo que la cruz del recap en la app') and a procedural instruction ('Pedí confirmación antes'), but never states when to prefer this over confirm_meeting_actionable or how it differs semantically from a task deletion. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=false. The description usefully clarifies that this is an unlink operation on a document's knowledge graph rather than entity deletion, but it does not say whether unlinking is reversible, whether the entity/document remain intact, or what permissions are needed.

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 front-loaded sentence with no filler or redundant text. Every word contributes to stating the action.

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 combination of 100% schema coverage and annotations covers the safety profile, and the description states the core action. However, for a destructive mutation with no output schema, it omits important context such as reversibility and the effect on the entity/document, leaving gaps.

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

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

Schema description coverage is 100%, and all three parameters have descriptions. The tool description adds no parameter-level meaning beyond the schema, such as workspace_id fallback behavior, so the baseline of 3 applies.

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 verb ('Desvincula') and resource ('una entidad del knowledge graph de un documento'), so the action is clear. It does not explicitly name or distinguish from sibling tools such as associate_document_entity, so it falls short of 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?

Only describes the action itself; there is no when-to-use guidance, no exclusions, and no explicit comparison to alternatives like associate_document_entity or delete_entity_relation. Usage is implied by the name but not explained.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description goes beyond them by disclosing the returned fields (id, name, workspace, parent_document_id, updated_at) and the cross-workspace, single-call scope — meaningful context given there is no output schema. It does not mention limits or ranking of results.

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 short, front-loaded blocks: purpose/scope, return shape, then usage and disambiguation. Every sentence carries information and nothing is repeated.

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, the description correctly enumerates the return fields; with annotations covering safety, the remaining burden is scope, trigger condition, and ambiguity handling — all present. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters are documented there, so the baseline is 3. The description only reinforces that matching is by name (consistent with 'Parte del nombre del documento') and says nothing about the limit parameter or default of 30.

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

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

The description states a specific verb and resource with an explicit scope: search documents BY NAME across ALL the user's workspaces in a single call. That scope distinguishes it from workspace-scoped siblings such as get_documents or get_documents_by_entity, though it never names a sibling explicitly.

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 a concrete triggering condition (the user names a document and its workspace is unknown) and even prescribes follow-up behavior for ambiguous results ('si vuelve más de uno con nombre parecido, preguntá cuál antes de escribir'). It stops short of naming an alternative tool or stating 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 establish readOnlyHint=false and destructiveHint=false; the description adds the valuable idempotent behavior that if nothing is pending it simply returns the version the artifact ended up in. It does not mention any permission or workspace-auth requirements, which is a minor residual gap.

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 compact sentences, with the strong 'almost never needed' caveat front-loaded and the fallback case clearly appended. No filler, though the deprecation framing precedes the actual action.

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 3-parameter finalize tool with no output schema, the description supplies the pending/legacy context, the idempotent outcome, and the routing against start_artifact_upload. Enough to call it correctly, with only auth/environment prerequisites left implicit.

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 100%, so artifact_id, nota and workspace_id are already documented in the schema. The description adds no further parameter meaning, making the baseline 3 correct.

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 says the tool exists for old uploads that left the file waiting, and that it reports the resulting artifact version, which conveys the finalize-a-pending-upload action. It leans on the title and on referencing the start_artifact_upload sibling rather than stating the verb directly, so it is clear but not fully self-contained.

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

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

It explicitly covers when not to use it ('Ya casi nunca hace falta: el PUT de start_artifact_upload deja el artefacto guardado solo') and when it is still needed ('las subidas viejas, que dejaban el archivo esperando'). The alternative behavior is named, so routing is unambiguous.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/write nature is covered. The description adds genuine value beyond that: the ~15-30s latency, that the result is persisted and retrievable afterward, and that 'monthly' costs more tokens/time. It does not detail auth/permission needs, which keeps it from a 5.

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?

Nicely structured and front-loaded: purpose first, then timing/persistence, then a type list, then usage trigger. Slightly verbose with some restatement, but every section earns its place for a tool with three modes.

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 costly generation tool with no output schema, the description covers all an agent needs: what it does, how long it takes, that the result is stored and retrievable elsewhere, the mode differences, and that it returns the content directly. Nothing material 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema's bare enum by explaining what each type produces (daily = today's summary/tasks/notes; weekly = trends/highlights; monthly = full analysis with more tokens/time). The workspace_id parameter is left to the schema, which is acceptable given full coverage.

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

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

States a specific verb (generate) and resource (a new AI report of the workspace), and enumerates the data sources it analyzes (daily notes, completed tasks, recent activity). It is clearly distinguishable from sibling read tools get_reports/get_last_report, which are explicitly named as the retrieval endpoints.

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?

Gives an explicit trigger ('Usar cuando el usuario pide "generá un reporte"...') and clarifies the relationship to alternatives: generation here, retrieval via get_reports/get_last_report once finished. The 15-30s timing sets expectations before invocation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: omitting workspace_id fans out across ALL of the user's workspaces with per-item attribution, and the default day is the user's timezone, not UTC, with a concrete Buenos Aires/21hs example. It stops short of describing return shape or item ordering, so a 4 rather than 5.

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?

Front-loads the core purpose in the first sentence, then layers scoping constraints and the timezone caveat in descending order of importance. Every sentence carries a distinct instruction; none is filler.

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

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

For a zero-required-parameter read tool with no output schema, the description covers everything an agent needs: what is aggregated, workspace scoping, multi-day usage, and the timezone default. No output schema exists, so return-value explanation is not required.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it explains that workspace_id omission means an all-workspace fan-out, that date+hasta together express a multi-day window (with the Monday-to-Sunday week pattern), and that date defaults to today in the user's timezone. This is more than restating the schema.

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

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

States a specific verb+resource (retrieve the day's/multi-day agenda) and enumerates exactly what it aggregates: calendar events, due tasks, still-open overdue tasks, and upcoming reminders. It explicitly distinguishes itself from the siblings get_events and get_tasks by naming them as the manual alternative it replaces.

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?

Gives explicit when-to-use ('¿qué tengo hoy/mañana/esta semana?') and multiple when-NOT-to-use rules: don't call once per workspace, don't call one day at a time, and don't bolt on get_events or get_tasks for the same data. The alternative and the condition selecting it are both named.

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

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

Annotations already declare readOnly/openWorld/destructive flags. The description adds return-field detail and workspace-scoped listing, which is useful context beyond annotations, but does not discuss pagination side effects or auth requirements. With annotations covering safety, a 4 is appropriate.

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

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

Two compact sentences: purpose first, return fields second, alternative third. No waste, front-loaded.

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

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

No output schema exists, so listing return fields is valuable. With schema documenting all parameters and annotations covering safety, the description gives an agent enough to call correctly; pagination details are covered by the schema.

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 100%, so the schema already documents limit, offset, and workspace_id. The description adds no parameter syntax or meaning beyond the schema, so baseline 3 is correct.

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?

Specific verb 'Lista' plus resource 'todos los archivos subidos al workspace' and explicit return fields. It distinguishes itself from get_storage_usage by naming that sibling for storage totals. Workspace-wide wording separates it from document-specific file listing 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?

Provides one explicit alternative: use get_storage_usage for total storage. It does not state when to prefer this over get_document_files or other file-listing siblings, so guidance is clear but incomplete.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavioral context beyond them: token cost of each mode, that content responses also carry `bytes` and `sha256` for verification, and that 'buscar' reports the match count that matters before patching. This is genuinely useful operational detail.

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?

Front-loads the core purpose, then uses a compact bulleted structure to contrast the two modes; every claim (cost, paste-compatibility, occurrence count) earns its place. It is dense and slightly long, but not padded.

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, so the description correctly carries the return-value burden: metadata, version history, returned fragments, and the `bytes`/`sha256` fields when content is included. All six parameters are covered and the read-only nature is clear, 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?

Schema coverage is 100%, so the schema already documents each field, establishing a baseline of 3. The description goes further by giving cross-tool semantics for 'buscar' (its output pastes directly into patch_artifact's `buscar`) and clarifying the literal-not-regex reading path, adding value beyond the schema.

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

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

States a specific verb and resource ('Trae un artefacto') plus exactly what is fetched (metadata and version history), then enumerates the two content-retrieval modes. An agent can distinguish this from get_document, list_artifacts, or patch_artifact without opening the schema.

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?

Gives clear when-to-use guidance for each mode: 'buscar' is framed as the read-for-edit path with an explicit cost comparison (~800 vs 107,000 chars) and a direct hand-off to patch_artifact; 'incluir_contenido' is flagged as expensive and reserved for full reads. It does not, however, contrast the tool against adjacent retrieval siblings (get_document, list_artifacts) for tool-level choice.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, non-open-world), yet the description adds genuinely useful behavior: the dynamic entry/exit rule for boards, the id prefix convention (`tb` vs uuid), and especially the `prestado` visibility limit ('lo único que podés ver es lo que entra en ese tablero, nada más del workspace'). It omits pagination/ordering 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?

Front-loaded purpose followed by structured bullets for the three types, each sentence adding distinct information. It is longer than typical, but the length is largely justified by an unusual domain concept that the schema cannot express.

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, one optional parameter, and annotations covering safety, the description supplies the domain model, the type taxonomy, the id conventions, and the next-step tool. It could still hint at what fields are returned (name/id only), a minor gap.

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 100% and the single parameter is already documented as UUID-or-name with omission meaning all workspaces. The description adds nothing about workspace_id, so the baseline of 3 applies.

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 resource (tableros / saved named views of tareas) and the scope (the ones this person can open), then defines what a board actually is so the agent can distinguish it from plain task lists. It explicitly hands off to get_board_tasks for contents, separating boards from the tasks inside them.

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?

Gives clear context on the three board types and states the follow-up tool ('Para ver qué tareas tiene adentro: get_board_tasks'), which routes the agent correctly. It does not, however, say when to prefer this over get_tasks or other listing tools, nor any exclusion beyond the sharing caveat.

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 readOnly/non-destructive annotations, the description discloses genuinely useful behavior: results are computed on the fly (not cached), the borrowed-board result set is governed by board permission rather than workspace membership, foreign-task output is trimmed (no recap source, only name/type/color for Atlas entities), and private tasks are always excluded. This is exactly the kind of context annotations cannot carry.

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?

Front-loads the most important insight (computed vs. stored list) and each subsequent sentence contributes concrete behavioral detail. Slightly dense with the trimming/permission clauses, but every sentence earns its place.

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

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

With no output schema, the description compensates well by describing the shape of trimmed results and the evaluation semantics. For a read-only tool this is nearly complete, though a note on result volume/ordering would close the remaining gap.

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 100%, so board_id, workspace_id and incluir_cerradas are already fully documented in the schema. The description adds no syntax or format detail about the parameters, so the baseline 3 is appropriate.

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 verb (ver/obtener) and resource (tareas dentro de un tablero), and crucially clarifies that it is a live-evaluated, rule-resolved view rather than a stored list. This scoping to a board distinguishes it from the general get_tasks / get_declared_tasks, but it never names a sibling explicitly to route the agent.

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?

Gives clear context for when the tool applies: own board (private or shared) and boards borrowed from another person, with an explanation of how the set is decided in the borrowed case. It stops short of stating when NOT to use it or pointing to the alternative task-listing tools.

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

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

Annotations already declare readOnly/non-destructive safety, so the bar is lower. The description adds real value by explaining that the 'content' field is the serialized whiteboard state — useful since there is no output schema — though it omits return format details like size or pagination.

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 tight sentences, front-loaded with the action and scope, followed by a clarifying note about the content field. No wasted text.

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, the description partially compensates by explaining what the returned 'content' holds, and annotations cover the safety profile. It is largely sufficient for a single-resource read tool, missing only minor format expectations.

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 100%, so both canvas_id and the workspace_id semantics are already documented in the schema. The description adds no parameter meaning beyond that; baseline 3 applies.

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 verb+resource ('Obtiene un canvas') and clarifies it returns the complete content (nodes/edges JSON). It contrasts implicitly with get_canvases (plural list) and create/update/delete_canvas, but never names those siblings to differentiate explicitly.

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 is implied by the verb and the returned content, but there is no explicit when-to-use guidance, no exclusions, and no pointer to get_canvases for listing vs. this single-fetch. Adequate but leaves 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by disclosing the return shape: metadata only, no canvas content — the key behavioral fact for choosing this over get_canvas.

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 tight sentences with zero waste, front-loading the core action first and the routing hint last. Every sentence earns its place.

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

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

With annotations covering the safety profile, full schema coverage, and no output schema, the description carries the remaining load: it names the resource, the return scope (metadata, not content), and the alternative for full content. Nothing needed 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?

Schema description coverage is 100% and all three parameters (limit, workspace_id, parent_document_id) are documented there, so the schema does the heavy lifting. The description only implies workspace scoping via "del workspace" and adds no syntax or default details beyond the schema.

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

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

States a specific verb ("Lista") and resource ("canvases del workspace") with a clarifying gloss (whiteboard/diagrama visual). It distinguishes itself from the singular sibling get_canvas by name, so an agent can route without opening either schema.

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?

Explicitly routes to the alternative: "Para ver el contenido completo de un canvas: usar get_canvas(canvas_id)", giving a clear condition for choosing between the two. It stops short of stating the inverse (when listing is preferred over other lookups), leaving slight 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Because there is no output schema, the description usefully compensates by disclosing what data comes back (full markdown text plus summary and key points), which goes beyond the annotations.

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

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

A single compact phrase with zero filler, and the most important content (what the clip contains) is front-loaded. It is slightly odd as a bare noun phrase rather than a clause, but nothing needs to be trimmed.

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 two-parameter read tool with full schema coverage and complete safety annotations, the main missing piece is return-value explanation — and since no output schema exists, the description does supply it (markdown text, summary, key points). The only real gap is routing guidance against get_clips.

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 100%, so clip_id and workspace_id are already documented (including the cross-reference to get_clips and the workspace UUID/name semantics). The description adds nothing about parameters, so the baseline 3 applies.

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 (a single clip) and specifies what it returns — full markdown text, summary, key points — so the agent knows this is a single-item fetch versus the list-oriented get_clips. However, it is a noun phrase with no explicit verb ('retrieve/fetch') and never names the sibling it complements, so it falls short of full sibling differentiation.

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 no when-to-use guidance and no named alternative. The description never tells the agent to use get_clips to discover IDs or when this tool is preferred over get_clips; the only hint ('de get_clips') lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it warns the list deliberately omits full text to avoid flooding the response, and names which fields (content_md, summary, key_points, clip_mode) the payload carries.

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?

Purpose is front-loaded in the first line and the routing hint sits at the end. The middle paragraph explaining clip fields is useful context rather than filler, though the conceptual framing ('material de AFUERA') is slightly expansive for a list 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?

There is no output schema, so the description carries the burden of describing return values — and it does, naming the content fields and the clip_mode distinction. The remaining gap (no mention of default limit or pagination behavior) is minor since the schema covers limit.

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 100%, so limit, query, source and workspace_id are already documented in structured data. The description adds no parameter-level detail (e.g. filtering behavior or multi-workspace semantics), so baseline 3 applies.

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?

Opens with a concrete verb+resource ('Los clips del workspace') and immediately scopes what a clip is (páginas guardadas / mails reenviados). It also distinguishes itself from the closely-named sibling get_clip by stating this returns the list without full text. An agent can tell the two apart without opening either schema.

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?

Explicitly routes the agent to get_clip when a single clip's full text is needed ('pedí uno puntual con get_clip'), which is a clear when-to-use-this-instead instruction. It does not discuss when to use query/source filters or when listing is preferable to searching, leaving some 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 establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavioral context beyond that: the tool is unavailable to sb_* token types, an auth-scope limitation an agent could not otherwise anticipate.

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 front-loaded sentence with no filler; the scope (completed tasks, authenticated user) comes first and the availability caveat second.

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?

Annotations cover safety and the schema covers both parameters, so the essentials are present. But there is no output schema and the description says nothing about the return shape (pagination, fields per task) or whether it overlaps with get_tasks, leaving minor gaps for a list tool of this kind.

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 100%, and the schema already documents both limit (max 200, default 50) and workspace_id (UUID or name, omit for all workspaces). The description adds nothing about parameters, so the baseline 3 applies.

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 verb ('Obtiene') and a specific resource subset ('las tasks completadas del usuario autenticado'), which distinguishes it from the generic get_tasks and get_declared_tasks siblings. It is clear what the tool returns, though it doesn't explicitly contrast itself with those 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?

The parenthetical restriction '(no disponible para tokens sb_*)' is a real usage constraint that tells the agent when the call will fail. However, it never says when to prefer this over get_tasks / get_declared_tasks, or whether filtering by workspace is required, so selection among siblings is left 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds real behavioral value beyond annotations: it states the 8000-char content cap, the empty/missing-note return behavior, and that summary/intelligence may be null. It does not mention auth or rate limits, but for a read-only note fetch that is minor.

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?

Front-loads the action plus default, then the return fields, then the edge case, then alternative routing. Every sentence earns its place and the size is proportionate to a tool with no output schema.

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, the description carries the burden of explaining the return shape and does so field-by-field, including nullable fields and the empty-result case. 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?

Schema description coverage is 100%, and the schema already fully documents both date (format, default) and workspace_id (UUID or name, omit = all workspaces in one call). The description only restates the today default and adds no syntax or filtering detail beyond the schema, so the baseline 3 is correct.

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 verb and resource (obtain the daily note for a date, default today) and defines what a daily note is. It explicitly distinguishes itself from the sibling tools search_daily_notes and get_recent_notes, so an agent can route without opening schemas.

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?

Gives an explicit alternative and the condition that selects it: 'Para buscar en notas de varios días, usar search_daily_notes o get_recent_notes'. It also notes the default date behavior and the missing-note case, leaving little 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real behavioral context beyond that: records are provisional, back no `tasks` row until confirmed, and `missing_date`/`missing_owner` explain why an item stalls waiting. It does not mention pagination or ordering.

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 core definition is front-loaded in the first line. The remaining paragraphs earn most of their space by explaining the provisional lifecycle, though the 'no row in tasks / doesn't appear in get_tasks' idea is stated twice, which is mild redundancy.

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

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

There is no output schema, and the description ably covers the return model for a read-only list tool (provisional segments, extraction fields, confidence, db_task_id, missing_date/missing_owner). Combined with 100% schema coverage on the four inputs, an agent has enough to call it correctly; only list behavior (pagination/ordering) is unaddressed.

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 100% — limit, note_date, pendientes, and workspace_id are all documented in the schema, including the default and the omit-means-all behavior. The description adds nothing about parameters (the fields it names, missing_date/missing_owner/db_task_id, are return fields, not inputs). Baseline 3 is correct.

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 resource with scope: provisional tasks scraped from daily notes that have no row in `tasks` yet. It explicitly distinguishes itself from the sibling get_tasks ('por eso no aparece en get_tasks'), so an agent can route correctly without opening either schema.

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 context for when this tool is the right one — provisional items are exactly the records get_tasks will not return — and explains the lifecycle (confirmation makes `db_task_id` point to the real task). It stops short of an explicit when-to-use/when-not clause, but the alternative is clearly implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond restating the purpose: no note on whether unfiltered calls return all workspaces, how 'definitions' are composed, or any rate/size 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?

A single short sentence with no filler, though its brevity comes at the cost of under-specification rather than efficient density.

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 four parameters, no output schema, and an undefined core concept ('definiciones'), the description is too thin. An agent cannot tell what a definition record contains or how results differ when entity_id is applied, and there is no output shape to fall back on.

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 100%, so limit/offset/entity_id/workspace_id are all documented in the schema itself. The description's only contribution is echoing the optional entity filter, which the schema already states more precisely (including the 'omit = ALL workspaces' behavior). Baseline 3 applies.

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?

It states a verb and resource ('Obtiene las definiciones del workspace'), but 'definiciones' is never defined and the tool overlaps conceptually with siblings like get_knowledge, get_playbook, get_guide, and get_entity_wiki, with nothing to distinguish them. The scope hint (workspace, optional entity filter) helps narrow it, but the core object of the tool remains ambiguous.

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 no guidance on when to use this rather than get_knowledge/get_playbook/get_entity_wiki, nor any prerequisite or exclusion stated. The phrase 'con filtro opcional por entidad' only hints at a filtering variant, not a usage decision.

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

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

Annotations already cover the read-only/safe profile, so the bar is lower. The description adds genuine behavioral context beyond them: that the response aggregates open/closed task counts per deliverable, that `summary` is AI-authored, and that `delivered_at` reflects actual delivery. No note on pagination or permissions, but the added data-provenance detail is valuable.

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?

Front-loaded with the core function, then a definition, a use case, and field clarifications. Every sentence carries information; slightly verbose but no filler.

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

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

There is no output schema, so the description carries the return-value burden and does so partially: it explains the task counts, `summary`, and `delivered_at`. It omits the full record shape and pagination behavior, leaving a small gap.

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 100% and the schema descriptions are already rich (workspace_id even explains omitting it means all workspaces). The description adds nothing about limit, status, or workspace_id, so the baseline 3 applies.

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 the resource (entregables del workspace) and the distinctive scope (each one with counts of open/closed tasks), and defines what an entregable is. It does not explicitly name how it differs from create_deliverable/update_deliverable, but the aggregation scope is specific enough to distinguish it.

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

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

Gives a clear use case: answering "¿cómo viene X?" without reading task by task. That tells the agent when this beats get_tasks. No explicit exclusions or named alternatives, so it falls short of 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?

With readOnlyHint/destructiveHint already declaring safety, the description adds substantial non-obvious context: it returns `updated_at` for optimistic-locking via `base_version` (writes fail rather than overwrite), and `perdidas` lists what markdown cannot represent and blocks patch_document/append_document when non-empty. These are exactly the behavioral traits an agent needs and cannot get from 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?

Purpose is front-loaded in the first line, then organized by parameter/mode with clear headings. It is somewhat long, but the length is justified by the several modes and formats; little is redundant.

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, so the description carries the burden of describing the return surface, and it does: content format, `updated_at`, and `perdidas` with their consequences. Combined with the annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully enriches the two key parameters: it spells out what each `format` value means and which are accepted by write tools, and clarifies `buscar` returns only matching fragments. It adds little for `contexto` and `workspace_id` beyond the schema, keeping it below 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?

Names a specific verb and resource ('Lee un documento') and states the default behavior precisely (returns markdown, once, without duplication). It references sibling write tools (create/update/patch/append, patch_document, append_document), but does not distinguish itself from the read-side siblings like get_documents, find_documents, or search_documents, which is the main ambiguity an agent would face.

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?

Gives concrete when-to-use guidance: use `buscar` on a long document to find out WHAT to change with patch_document, and use 'markdown' because it is what the write tools accept. It explains the role of 'crudo' as rarely needed. It lacks explicit routing against the other document-read/search siblings, but the internal guidance is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond that (no return shape, no pagination, no empty-result behavior), so it carries no incremental value.

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

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

A single short sentence with the resource front-loaded and zero filler. Nothing could be trimmed without losing the core meaning.

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

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

For a simple read-only lookup with full schema coverage, present annotations and no output schema, the description is minimally adequate. It is missing the disambiguation from the inverse tool get_documents_by_entity and any note on result scope, but nothing critical blocks 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?

Schema description coverage is 100% and the schema itself explains both document_id and the workspace_id fallback (UUID or spoken name). The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource: retrieving the knowledge-graph entities linked to a document. It is clear and unambiguous, but it does not differentiate itself from closely related siblings such as get_documents_by_entity (the inverse lookup) or associate_document_entity.

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 no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent must infer the usage context entirely from the sibling names.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond the name and annotation title ('Ver los archivos de un documento') – no pagination, result-size, or scoping behavior is disclosed.

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, front-loaded sentence with no waste. It is appropriately terse for a simple read-only list tool, though it is arguably under-specified rather than genuinely concise.

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

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

No output schema exists, so the description need not explain return values, and the annotations carry the safety profile. Still, for a list tool it says nothing about ordering, pagination, or empty results, leaving a small gap 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?

Schema description coverage is 100%: document_id and workspace_id are both fully documented in the schema, including the workspace UUID-or-name convention. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 verb ('Lista') and resource ('archivos adjuntos a un documento'), so an agent knows exactly what it does. However, it does not differentiate itself from close siblings like get_all_files or get_document, leaving the boundary to inference.

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 no when-to-use or when-not-to-use guidance and no mention of alternatives such as get_all_files or get_document. The agent must infer that this retrieves attachments for one specific document rather than all files.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful value beyond that by stating no content is returned and enumerating the exact metadata fields (id, name, date, updated_at, parent_document_id, order), which shapes how an agent plans follow-up calls.

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?

Front-loaded with purpose and scope, then a clean routing block, then parameter semantics. Every sentence carries routing or semantic value, though the parent_document_id explanation overlaps with the schema already.

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?

No output schema exists, yet the description compensates by listing the returned metadata fields, and the routing covers all obvious alternatives. An agent has everything needed to call it correctly and interpret the result.

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 100%, so the baseline is 3, but the description adds the subtle tri-state semantics of parent_document_id (omit = all, null = root only, specific ID = children) in a form slightly distinct from the schema wording. It reinforces rather than merely repeats the schema.

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

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

States a specific verb and resource ('Lista los documentos del workspace'), and immediately scopes it ('SIN contenido — solo metadata') with an explicit field list. It is clearly distinguishable from get_document, search_documents, and find_documents, which it names directly.

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?

Gives explicit when-to-use scenarios (navigate structure, list documents, find IDs) and routes each adjacent case to the right sibling: get_document for content, search_documents for content search, find_documents for name lookup in unknown workspaces. Nothing is left to inference.

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