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

Beyond the destructiveHint=true annotation, the description discloses the concrete behavior: it reads current values, resolves catalogue names, and 'never removes an existing value without confirm_delete:true.' It also explains that dry_run previews catalogue resolution and removals without writing, which is exactly the operational detail an agent needs for a destructive 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?

Three sentences, front-loaded with purpose followed by scope and safety semantics; no filler. Slightly dense but every sentence carries information about behavior.

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

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

For a destructive mutation tool with no output schema, the description covers scope, ordering semantics, the confirm_delete guard, and the dry_run preview, which is enough to call it correctly. It stops short of describing what a successful run returns, but that is a minor gap given the otherwise thorough coverage.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters including dry_run and confirm_delete. The description reinforces the dry_run/confirm_delete semantics but adds no syntax or format detail the schema lacks, 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 scope: 'Complete the post-save CvLAC phase for an existing product,' then enumerates the managed sub-resources (keywords, areas, coauthors, recognitions, thesis students). This is far more than a restatement of the name, though it never explicitly names or contrasts a sibling like update_section.

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 workflow guidance ('Use dry_run:true to preview...', confirm_delete needed for removals), which tells the agent how to invoke it safely, but it never states when to reach for this tool versus read_cvlac, update_section, or sync. Usage context is implied 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=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the four result buckets and flagging that 'similar' entries require human judgment, which is meaningful since no output schema exists.

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

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

Two sentences, zero waste, with the core purpose front-loaded and the return structure following immediately after. Every clause carries information.

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

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

With no output schema, the description must carry return-value meaning, and it does list the four buckets. However, it never states the direction of the diff (missing from which side) or what distinguishes 'missing' from 'toUpdate', leaving a real ambiguity for a comparison 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% and the single section parameter has an exhaustive enum, so the schema fully documents the input. The description adds no semantics about the section filter, 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?

The description gives a specific verb (compare) and both resources (CvLAC vs portfolio), so the agent knows exactly what the tool operates on. It does not explicitly name the sibling sync or explain how this differs from it, 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?

Usage is only implied: comparison-before-action, with 'a human decides' hinting at decision support rather than automated sync. There is no explicit statement of when to choose this over sync or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description usefully adds that the tool performs a network navigation and returns raw HTML of form elements. It omits auth/session requirements, which matters given a sibling 'login' tool exists, and says nothing about rate limits or fetch failures.

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

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

A single front-loaded sentence with the action first and the return payload second; nothing is wasted. It is appropriately sized for a one-parameter debugging 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 simple one-param tool with annotations covering the safety profile and no output schema, the description tells the agent both what it does and what it returns. Only the auth/network-side-effect details are 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?

There is only one parameter and schema description coverage is 100%, so the schema already documents it fully. The description reinforces that the URL must be a CvLAC URL, but adds no format or syntax detail beyond that.

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+resource: it navigates to a CvLAC URL and returns the HTML of form inputs/selects/textareas. This clearly separates it from content-reading siblings like read_cvlac or read_portfolio, though it never explicitly names those alternatives.

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?

'for debugging field names' states a concrete use context, so an agent knows this is a diagnostics/introspection call rather than a data-retrieval one. It stops short of naming when NOT to use it or pointing at a sibling alternative.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this mutates state without being destructive. The description usefully adds that the session is persisted, but says nothing about where credentials come from, what happens on failed authentication, or whether re-login invalidates an existing session.

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 verb, the target system, and the persistence side effect with zero 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 a trivial one-parameter schema, full schema coverage, and annotations covering the safety profile, the description is close to sufficient. The remaining gap is meaningful for an auth tool: it never explains credential sourcing or failure/lockout behavior, which an agent needs before invoking login.

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 optional 'force' parameter is fully documented in the schema itself ('Force re-login even if session is valid'). The description adds no parameter-level 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?

States a specific verb and resource ('Authenticate in CvLAC') plus the side effect of persisting the browser session. No sibling tool performs authentication, so it is inherently distinct, but the description does not explicitly claim that uniqueness.

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 or when-not-to-use guidance and no mention of alternatives or prerequisites relative to the read_*/update_* siblings. The mention of persisting a session only weakly implies this must precede session-dependent calls.

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, and the description reinforces this consistently ("Read-only", "does not write to CvLAC"). It adds useful context that the output is a draft requiring human/agent review before being written, though it says nothing about failure modes such as unresolvable DOIs or network limits.

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 tight sentence that front-loads the read-only nature and the purpose, then the workflow handoff. No filler and nothing repeated from the 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?

For a one-parameter read tool with no output schema, the description covers the input source, the read-only guarantee, and what is returned (an article draft), plus the next step. Nothing essential for correct invocation 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 single doi parameter already documents accepted formats (DOI, doi:..., https://doi.org/...). The description adds no additional syntax or handling 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 (look up), resource (a DOI in Crossref) and the result (an article draft), and distinguishes itself from siblings by declaring it does not write to CvLAC and by naming update_section as the follow-up tool.

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 workflow: review the returned draft, then pass it to update_section with section:"articulos". It also states the boundary condition (this tool does not write to CvLAC), so the agent knows exactly where this tool's role starts and stops.

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 the safe-read profile is covered. The description adds a scope note that list results include every JMesa page and that output is suitable for comparison, but gives no pagination, volume, or failure behavior. Adding some context on top of annotations merits a 3.

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 with the resource and scope front-loaded and no filler. The trailing clause about JMesa pages is slightly cryptic but still earns its place by clarifying output scope.

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 single-parameter read tool with full schema coverage, annotations, and no output schema, the description covers the essentials. It is adequate but leaves the key ambiguity unresolved: how it differs from read_cvlac_detail and what 'five kinds of technical production' maps to in the enum.

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 section parameter is fully enumerated with a documented default, so the schema carries parameter meaning. The description's section list ('articles, books, chapters, theses, juries') maps only loosely to enum values and adds no syntax or default details. 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 (Read) and resource (current CvLAC sections) and enumerates the content types returned (articles, books, chapters, theses, juries, technical production). It does not differentiate itself from the sibling read_cvlac_detail, so an agent must infer which read tool to pick.

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?

"Returns existing items for comparison" implies the intended workflow (fetch current state before diffing/updating), which is a useful usage hint. However, no explicit when-to-use, when-not, or named alternative (e.g., read_cvlac_detail vs read_cvlac) is given, leaving selection 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 matching semantics (finds the row by label, case- and accent-insensitive) and enumerates what is revealed (role, dates, institution, financing), 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?

Three short sentences, front-loaded with the core purpose and the reason to prefer it over list views. No wasted filler, though the parenthetical field list is slightly list-heavy.

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 read-only detail tool with no output schema, the description conveys the return content and matching behavior. The main gap is lack of documented semantics for the section enum, which the schema leaves bare.

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 50%: label is described in the schema but section is only an enum. The description clarifies that section identifies the list and that label is the name/title as it appears there (e.g. degree for formacion), adding modest value but not fully compensating for the undocumented section values.

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: 'Read the full record page of one CvLAC item.' It distinguishes itself from the list views by contrast, though it doesn't name the sibling tool (read_cvlac) explicitly, leaving differentiation partly implicit.

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

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

Provides clear context for when to use it — to see the fields a write actually stored, since list views only show a couple of columns. No explicit when-not or named alternative, but the intended use case 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 establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description contributes the useful disclosure that output is a merge of a remote site and a local curated file, which explains non-obvious result composition, but it says nothing about caching, network failure behavior, or return 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?

A single front-loaded sentence that carries the source information with no filler. It is appropriately sized for a no-argument read tool, though the parenthetical file reference is slightly dense.

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

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

With no output schema and no parameters, the description is the only place an agent could learn what comes back. It identifies the data sources but not the returned structure (parsed site fields, the proyectos/software/eventos sections), leaving a moderate gap for a read tool that merges two sources.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly signals there is nothing to configure per call, other than implying PORTFOLIO_URL is environment-level configuration.

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 gives a specific verb+resource ('Read and parse the configured portfolio site') and even names the underlying data sources (PORTFOLIO_URL, data/portfolio-extra.json). That distinguishes it from read_cvlac and read_profile, though it does not 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?

No when-to-use or when-not-to-use guidance is provided. An agent cannot tell from the text whether this should be preferred over read_profile or read_cvlac, or whether it must be preceded by login.

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 useful scope context by naming the exact content types retrieved, but says nothing about authentication requirements, pagination, or what happens when a profile field is empty.

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 key scoping claim ('record instead of a list') comes first. Slightly dense with the parenthetical list, but every clause carries information.

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

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

With no output schema and no parameters, the description compensates by enumerating the returned content (profile text, social networks table, áreas de actuación). That is adequate for a parameterless read tool, though a note on behavior for missing fields would complete it.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly does not fabricate parameter guidance.

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

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

States a specific verb (Read) and resource (CvLAC profile pages) and explicitly scopes the content to fields that are single-record rather than list-based. It also names the sibling read_cvlac as the place these fields do NOT appear, aiding disambiguation. Minor ambiguity: it says 'two pages' but then enumerates three distinct items (profile text, social networks table, áreas de actuación).

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 one negative routing cue ('None of them appears in read_cvlac'), which implies when to prefer this tool, but never states a positive when-to-use condition or contrasts against other siblings like read_cvlac_detail or read_portfolio. Usage is implied rather than explicit.

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

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

Adds real behavioral context beyond the readOnlyHint/destructiveHint annotations: action links (delete, save) are refused because merely opening them in CvLAC performs the action, and the capture reflects the page 'as it is now' (live reload, not cached). It doesn't describe the returned artifact (image vs. path) or any rate/latency concerns.

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 with no filler; the core action and its default are front-loaded, and the constraint clause follows logically. Every clause carries information.

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

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

For a single optional-parameter read-only tool with no output schema, the description covers action, default resolution, and the key side-effect safeguard. The only gap is what the capture actually returns, which is largely self-evident for a screenshot tool but not stated.

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 url parameter and its default are already documented. The description reinforces the default ('or else the last list, record or form page a tool visited') and clarifies which page types qualify, but adds no new syntax or format detail 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 ('Capture a CvLAC page') plus intent ('for debugging'), so an agent knows this renders a page rather than reading its content. It doesn't explicitly distinguish itself from siblings like read_cvlac or inspect_form, but the differentiated 'screenshot' verb is inferable.

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

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

The description explains the default behavior (falls back to the last list/record/form page a tool visited), which is useful invocation context, but it never states when to choose this over read_cvlac, read_cvlac_detail, or inspect_form. Usage is implied rather than stated with alternatives.

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

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

Annotations already flag destructive=true and readOnly=false, so the write profile is known. The description adds real value beyond that: preview-by-default, and the safety rule that ambiguous/duplicate-looking entries are never written but surfaced for human resolution.

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, front-loaded with what it does, followed by the safety rule and the invocation detail. 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?

No output schema exists, yet the description conveys the outcome semantics (unambiguous items written, ambiguous items listed for human review) and the default/override behavior. It does not describe any return payload structure, which is the only 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 coverage is 100% and the schema already documents dry_run's default and meaning. The description reinforces the dry_run:false invocation but adds no new syntax or constraints for 'sections', 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 action (run a full diff and apply unambiguous items) on a specific resource (CvLAC entries), and contrasts implicitly with the sibling 'diff' by emphasizing that sync applies changes. The domain terms 'missing + toUpdate' are precise. It is clear but never explicitly names the sibling it differs from.

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 useful behavioral guidance (default preview, dry_run:false to apply, ambiguous items deferred to a human), which implies when to use it over 'diff'. However it never states when to prefer 'diff' or 'update_section', so the agent must infer the 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?

Goes well beyond the destructiveHint=true annotation: networks are MERGED (reads existing state first and posts everything back because the form rewrites the whole table), areas are replaced whole so omissions count as removals, and confirm_delete gates all deletions. This discloses exactly what gets destroyed and the read-then-write mechanics.

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 dense but purposeful sentences on merge/removal semantics. Every sentence carries a distinct constraint; it is 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?

For a mutation tool with no output schema, it covers what is overwritten, deletion gating, the non-blankable profile text, and the ambiguity fallback. It omits any permission/auth requirements, which is a minor gap given the destructive nature.

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 cross-parameter semantics the schema does not: the read-modify-write behavior behind the merge, the confirm_delete gate shared by url:null and areas removal, and the 'choices' fallback for ambiguous names. This meaningfully augments the per-field schema text.

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 (write) and resource (researcher profile text and academic social networks), and distinguishes itself from read-oriented siblings like read_profile and read_cvlac. An agent can identify the tool's scope immediately.

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?

Explains the conditions that govern use: url:null removes a network, confirm_delete:true is required for removals, and the profile text cannot be blanked. It does not explicitly contrast itself with update_section or sync, but the operational context is clear.

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

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

Far exceeds the annotations: it discloses the needs_confirmation contract for adds, deletes and ambiguous pickers, that nothing is written until confirmed, that up to ~200 institutions can match a picker, that choices come back in 'choices', and that coauthors/keywords must be completed on the website. This is exactly the behavioral context annotations (destructiveHint) cannot convey.

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

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

Front-loaded with purpose, then confirmation flows, then section payloads – a logical order. It is dense and runs long as a single block with some very long sentences, but essentially every clause adds actionable information, so little 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?

There is no output schema, yet the description supplies the return contract (status 'needs_confirmation', 'choices'). Combined with the confirmation semantics and per-section payload rules for a 21-value section enum, an agent has enough to invoke this correctly without further probing.

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 only 60% and the key 'data' param is an unconstrained additionalProperties object, so the description carries real burden. It enumerates the per-section field requirements and the catalogue-id keys (revistaId, libroId, editorialId, programaId, areaId, institucionId) that the schema cannot express, plus the 2 MiB PDF constraint.

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 ('Apply a single change to a CvLAC section') and immediately scopes it with the screenshot confirmation behavior. An agent can tell this is the write/mutation tool versus the read siblings (read_cvlac, read_portfolio) and the higher-level sync/complete_product tools.

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

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

Gives rich when-to-use detail for each action and section (add/update/delete, plus per-section required fields), and explains how to resolve confirmation states. It never names an alternative sibling or states when NOT to use this tool (e.g., versus complete_product or sync), so it stops 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.