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

With no annotations, the description carries the full burden and does a fair job: it discloses that the tool is a WRITE OPERATION, that the provenance header is added automatically (so the agent should not include it), and that a comment write scope is required. It stops short of describing append-vs-overwrite behavior or failure modes.

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

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

Three tight sentences with the operation and its automatic header behavior front-loaded, and no filler. Slightly compressed given the undocumented parameters, but efficient per sentence.

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?

An output schema exists, so return values need not be explained, and the description covers the essentials: write classification, required scope, and the auto-generated header. The main gap is entity_type semantics and valid values, which are undocumented in both schema and description.

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

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

Schema description coverage is 0% for all four parameters, so the description must compensate and largely does not. Only trace_id gets indirect meaning via the 'trace: …' header notation; entity_type, id, and comment are left entirely to the bare schema titles.

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 (attach) and resource (AI-generated review comment) and names the target domain (eLabFTW experiment or item), which is clear and concrete. It does not distinguish itself from the sibling review_experiment tool, which an agent might reasonably confuse it with.

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 the write scope requirement ('requires the comment write scope') and flags the operation as a write, giving some context for use. However, there is no guidance on when to reach for this versus review_experiment or how it fits into a review workflow.

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 no annotations, the description carries the full burden and largely succeeds: it flags WRITE OPERATION, names the required 'step write scope' permission, and discloses a non-obvious quirk (the create endpoint only stores the body, so deadlines require a follow-up update). It omits error/rate-limit behavior and whether deadline_notif triggers notifications, keeping it 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?

Three tight sentences, front-loaded with the core action and scope, then the write/permission caveat, then the deadline quirk. 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?

An output schema exists, so the explicit return-value sentence is largely redundant, and the description is otherwise adequate for the write itself. However, with zero annotation and zero schema-description coverage, leaving 'deadline_notif' and the deadline-assignment behavior only partially explained is a real 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 0%, so the description must compensate for all five params. It does add the deadline format (date/datetime string) and its stored-vs-applied behavior, and its entity-type list maps to the entity_type values, but 'id', 'body' and especially 'deadline_notif' remain unexplained.

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

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

States a specific verb (add) and resource (a step/task), and enumerates the exact set of host entities it accepts (experiment, item, experiment template, item type). This clearly separates it from sibling mutators like update_step, toggle_step and delete_step 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?

The description implies usage — it must be an existing entity, and it routes deadline setting to 'a follow-up update' — but it never states when to prefer this tool over siblings such as update_step or when a step should be created at all. Usage is inferable 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?

With no annotations, the description carries the full behavioral burden, and it does disclose the two most important facts: this is a WRITE OPERATION and it requires the tag write scope. It stops short of the remaining high-value disclosures — whether persistence appends to or replaces existing tags, whether it is idempotent, and whether it fails on duplicate tags.

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 the operation stated first and the critical constraint (write scope) second — well front-loaded with no filler. It is efficiently sized, though the second sentence is a fragment bolted on rather than integrated 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?

The presence of an output schema means return values need not be described, so the gap lies elsewhere: required-parameter semantics and the effect of re-applying tags are both missing for a mutation tool. Adequate but with clear gaps for a write operation with zero annotation coverage.

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

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

Schema description coverage is 0% across all three required parameters. The description only vaguely maps 'tags' and the entity ('experiment or item'), leaving 'id' entirely unexplained and giving no hint about the accepted values for 'entity_type' (which has no enum). With three undocumented required parameters, the description fails to compensate for the coverage gap.

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

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

States a specific verb ('Persist') and resource ('tags to an eLabFTW experiment or item'), which clearly separates it from the read-only suggest_tags sibling by virtue of the write semantics. The parenthetical '(suggested)' hints at the workflow relationship but the description never names suggest_tags directly, so sibling differentiation is implied rather than explicit.

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

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

The phrase 'a list of (suggested) tags' implies this is the persistence step following suggest_tags, so the intended usage context is weakly conveyed. However, there is no explicit when-to-use statement, no statement of what happens if tags already exist, and no stated alternative for a non-persisting path.

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 no annotations, the description carries the burden well: it discloses idempotency, that this becomes a WRITE OPERATION when dry_run=false, that the link write scope is required, and that results come back per-pair with a summary. It stops short of explaining partial-failure behavior despite the continue_on_error flag.

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 dense sentences, front-loaded with the primary action and the JSON payload format, with the write-scope warning mid-stream. Only the closing return-value sentence is slightly redundant given an output schema exists.

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

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

For an unannotated batch-mutation tool, the description covers the critical pieces: idempotency, the dry_run safety default, scope requirements, and payload shape. The remaining gaps (continue_on_error semantics, trace_id purpose and failure modes) are real but 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 coverage is 0% across 4 parameters, so the description must compensate. It defines the pairs_json element shape ({from_type, from_id, to_type, to_id}) and the write/read semantics of dry_run, but trace_id and continue_on_error are left entirely undocumented.

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

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

States a specific verb and resource ('remove several directed links'), plus a distinguishing trait (idempotent, batched in one call). An agent can separate it from delete_link and bulk_ensure_links without inspecting 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?

The batching scope is implied as the reason to use this over the single-link delete_link, and the dry_run default is surfaced, but there is no explicit when-to-use/when-not statement or named alternative. Minimum-viable routing guidance.

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

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

With no annotations, the description carries the safety burden and does so well: it declares idempotency, flags the write only under dry_run=false, names the required link write scope, and states the return shape. It does not explain failure behavior or what continue_on_error actually does, leaving one 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 tight sentences, front-loaded with purpose and the parameter contract before the operational caveat. Dense but every clause carries information; only a minor lack of labeling on the parameters keeps it from top marks.

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?

An output schema exists so return values need only a pointer, and the description gives purpose, idempotency, write semantics, required scope, and the batch limit. The residual gaps are the undocumented trace_id/continue_on_error semantics, which matter for a batch tool with error-handling options.

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

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

Schema coverage is 0%, so the description must compensate. It fully specifies the critical pairs_json parameter (JSON array shape, the four object fields, and the bulk_links_max_pairs bound), but trace_id and continue_on_error are never explained, leaving half the parameters opaque.

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 ('create several directed links in one call') and adds the defining trait 'idempotently', which separates it from the single-link sibling ensure_link and from bulk_delete_links. An agent can identify the tool 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 batching clause ('several ... in one call', plus the bulk_links_max_pairs cap) implies this is the multi-link path versus ensure_link, but the description never names the alternative or states the when-not condition. Usage is inferable 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?

With no annotations, the description carries the full burden and largely meets it: it flags this as a WRITE OPERATION, names the required create write scope, and discloses a refusal condition (force_exp_tpl). It stops short of describing failure/error behavior beyond that one gate or any side effects on templates/metadata, so it is strong but not exhaustive.

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?

Four short sentences, front-loaded with the write/scope requirement and escalating to prerequisites and refusal conditions. Every sentence carries distinct, load-bearing information with no filler.

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

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

An output schema exists and the description still confirms the return shape ('Returns the new id'). Combined with the write-scope, ID-discovery, and template-refusal guidance, an agent has what it needs to call this correctly; only the tags/body semantics remain thin.

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

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

Schema description coverage is 0%, so the description must compensate; it usefully explains that status_id/category_id must be discovered from valid IDs and warns against embedding IDs in title/body. However, it says nothing about tags, body content format, or the default 'Untitled' title, leaving several parameters undocumented in both schema and description.

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 (create a new eLabFTW experiment) and immediately contrasts itself with the template-based sibling by naming it. An agent can distinguish create_experiment from create_experiment_from_template without opening either definition.

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-not guidance: if force_exp_tpl is enforced the tool is refused and create_experiment_from_template must be used instead. It also states a prerequisite (look up valid category/status IDs first), which is actionable routing and preparation guidance 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?

With no annotations, the description carries the full load and does well: it declares this is a WRITE OPERATION, names the required create write scope, explains the copy semantics of the two boolean flags, and states the return value ('the new id'). It omits failure modes/permission errors, keeping it 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?

Four tight sentences, front-loaded with the action and the write/scope warning, with no filler. Every sentence adds 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?

Auth requirements, template discovery, flag semantics, and the return value are covered, and an output schema exists so return shape needn't be detailed. However, five parameters remain unexplained, leaving the definition incomplete for a tool with this many inputs.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate. It only explains template_id (indirectly) and the two include_* flags; tags, title, trace_id, status_id, and category_id are left entirely undefined in both schema and description.

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 ('Create a new eLabFTW experiment from an experiment template'), and the 'from template' qualifier clearly separates it from the sibling create_experiment.

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 routing guidance: the prerequisite tool (list_experiment_templates) for obtaining a template_id, plus the required write scope and the effect of the include_steps/include_body flags. An agent knows when and how to call 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?

With no annotations provided, the description carries the full burden and it does disclose the key traits: this is a WRITE OPERATION, it requires the create write scope, and it returns the new id. It does not cover failure behavior (e.g. invalid category_id) or reversibility, which are secondary for a create call.

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 purpose, then the write/scope warning, then the ID-hygiene rule. Every sentence earns its place; nothing is 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 5-param mutation tool with no annotations, the description covers the essentials (write nature, auth scope, ID discovery, return of new id) and an output schema exists so return details needn't be repeated. Only the tags/status_id parameters remain unexplained.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate. It clarifies category_id (item categories, IDs must be looked up) and warns against putting IDs in title/body, but says nothing about tags or status_id, leaving two parameters undocumented in both schema and prose.

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 (Create) and resource (a new eLabFTW database item/resource), and the parenthetical disambiguates it from experiment-creating siblings. An agent can distinguish it from create_experiment and create_experiment_from_template 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 real operational preconditions: requires the create write scope, items belong to item categories, and valid IDs must be discovered first rather than embedded in title/body. It stops short of naming the sibling tools (e.g. list_item_categories) that supply those IDs, but the when-to-use 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?

With no annotations, the description carries the full burden and does well: it discloses idempotency, that dry_run=false is a write requiring the link write scope, that dry_run=true merely reports, and it enumerates the result values. It does not cover auth-failure or error behavior, but the core mutation semantics are unusually well 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?

Three tight sentences, front-loaded with the core action and idempotency, followed by the write scope and return values. Every sentence adds distinct information with no waste.

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

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

An output schema exists, so the description needn't explain return values (though it does). Behavior for a mutation is well covered, but for a 6-parameter tool with 0% schema description coverage, the four required entity/type identifier parameters remain opaque, leaving a real 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 0% across 6 parameters, so the description must compensate. It only hints at the from/to direction via 'directed link' and reiterates the dry_run default already present in the schema; from_type, from_id, to_type, to_id, and trace_id remain unexplained, leaving most parameters undocumented.

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

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

States a specific verb ('remove') and a specific resource ('a directed link between an experiment and an item'), which distinguishes it from ensure_link and bulk_delete_links in the sibling list. It is clear and specific, though it does not explicitly name the alternative tool to route against, keeping it from 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 description clarifies the dry_run default and the consequence of each mode, which is genuine usage guidance. However, it never states when to prefer this over bulk_delete_links for multiple removals, so the when-to-use guidance 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?

With no annotations, the description carries the full burden and does disclose the key traits: it is an explicit WRITE OPERATION, it requires a specific write scope, and it returns status='deleted'. It omits irreversibility/cascade behavior and idempotency, but the mutation and auth posture are stated.

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

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

Two short lines, front-loaded with the action and scope, followed by the operation class and return value. No filler sentences.

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?

An output schema exists so return-value detail is unnecessary, and the description covers the write/auth posture. However, for a 3-required-parameter mutation with 0% schema coverage, the ambiguous id vs step_id semantics leave a real gap an agent could trip over.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: the four entity types map loosely to entity_type, but it never clarifies the distinction between id and step_id, both of which are required integers. Two of the three parameters remain unexplained in both schema and prose.

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 precise verb (delete) and resource (step) and scopes it to four eLabFTW entity types, which cleanly separates it from update_step, toggle_step, add_step and list_steps by intent. It stops short of explicitly naming those siblings, so it is clear but not maximally differentiated.

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?

States a prerequisite (requires the step write scope), which is useful context, but gives no when-to-use guidance versus alternatives like toggle_step or update_step, and no conditions under which deletion should be avoided. 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?

With no annotations, the description carries the full burden and does well: it declares the write operation, the required link write scope, the default-safe dry_run behavior, and the post-write verification. It still omits error/failure behavior and what happens with invalid or conflicting links, keeping it 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?

Three tight sentences, front-loaded with the core action and scope, then the write-mode warning, then the return contract. 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?

An output schema exists, so return values need not be spelled out, yet the description usefully names the result values anyway. For a mutation tool with zero annotations it covers safety and write scope well; the remaining gap is the undocumented input parameters.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate but only documents dry_run. from_type, from_id, to_type, to_id, and trace_id are unexplained, and the 'experiment and item' phrasing arguably conflicts with the generic type parameters.

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

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

States a specific verb and resource: 'idempotently create a directed link between an experiment and an item', with the idempotency and directedness qualifiers that distinguish it from a plain link-creation. It does not explicitly name siblings like ensure_link_by_query or bulk_ensure_links, so differentiation is implied rather than stated. The 'experiment and item' framing is slightly narrower than the generic from_type/to_type schema suggests.

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 explains the dry_run=false vs dry_run=true modes and their defaults, which is useful invocation guidance. However, it never says when to reach for this tool versus the obvious siblings (bulk_ensure_links, ensure_link_by_query), so tool selection 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?

With no annotations, the description carries the full burden and does a credible job: it flags a WRITE OPERATION, names the required link write scope, states idempotency, and explains ambiguity handling instead of silently guessing. It omits failure/error semantics beyond ambiguity and doesn't describe the dry-run preview return, but the safety-critical traits are covered.

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

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

Four tight sentences, front-loaded with the core action and then the constraints that matter most (capability limits, write scope, ambiguity policy). No filler or restatement of the name.

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

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

The mutation and ambiguity behavior are well covered, and an output schema exists so return values need not be explained. However, 15 parameters with 0% schema coverage leaves the bulk of the input contract undocumented, which is a substantial gap for a tool this wide.

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

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

Schema description coverage is 0% across 15 parameters, so the description must compensate and largely does not. It explains q, dry_run, and on_ambiguous, but leaves the filter params (tags, scope, owner_ids, status_ids, category_ids, offset, limit_candidates) and the from/to typing params entirely undocumented in both schema and description.

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 compound verb+resource: resolve an entity by query, then link it idempotently. The scope constraint ('works for experiments and items only') meaningfully narrows what the tool can target. It does not explicitly contrast itself with the sibling `ensure_link` (link by explicit id) or `resolve_entity_by_query`, so the differentiation is only implied rather than stated.

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 real conditional guidance: query resolution only applies to experiments and items, dry_run=false is when the write actually happens, and on_ambiguous controls ambiguity handling. It stops short of saying when to choose this over `ensure_link` or `bulk_ensure_links`, so alternatives are 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?

With no annotations, the description carries the full burden and does reasonably well: it declares 'Read-only', discloses hard constraints (max_depth capped at 3, node/edge/fan-out caps), and warns that truncation flags are returned. It omits auth/permission requirements and any rate-limit or pagination 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?

Dense but front-loaded: purpose, then parameters, then return shape, then safety. No wasted sentences, though the parameter run-on is packed tightly enough to risk being skimmable.

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

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

For a 13-parameter BFS graph tool, the description covers the semantics an agent needs to bound the traversal and interpret return values (an output schema exists, so return details need not be exhaustive). The unaddressed include_raw/include_node_summaries flags and absent auth notes are the remaining shortfalls.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for most parameters: direction values, the depth cap, the node/edge/fan-out caps, and the allowed_types/category_ids/status_ids/title_regex filters are all explained with their JSON-array/pattern format. It leaves include_raw, include_node_summaries, root_type, and root_id unexplained, which is a real but partial gap.

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

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

States a specific verb ('Build the directed link graph') and resource, plus the algorithm (BFS) and scope (around a root experiment/item). This clearly distinguishes it from the sibling get_entity_links, though the sibling is never 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?

Usage is implied by 'around a root experiment/item via BFS' – an agent can infer this is for multi-hop traversal. However, it never says when to use this versus get_entity_links or get_item, and gives no exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral trait: it is side-effect free and never writes. It also reveals the effective server mode (read-only vs write-enabled), which is meaningful context. It stops short of stating auth requirements or confirming idempotency/output shape beyond the field list.

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 verb and subject are front-loaded, and the trailing safety sentence is short and useful. The long enumeration of returned fields is somewhat list-heavy, especially since an output schema already exists, but it remains readable and earns most of its space.

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

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

For a zero-parameter, read-only introspection tool with an output schema, the description is essentially complete. The only redundancy is enumerating return fields the output schema already documents; otherwise nothing an agent needs to call it is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond what the empty schema already conveys.

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

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

The description uses a specific verb (Return) and resource (connection and session details), then enumerates exactly what is returned: base URL, authenticated user, active team, server mode, enabled tool groups, and category catalogue. An agent can tell precisely what this tool provides 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?

There is no guidance on when to call this versus siblings such as get_current_user_capabilities or refresh_team_caps, nor any stated precondition. 'Always safe to call' describes safety, not usage context, leaving the agent to infer that it is a bootstrap/diagnostic 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?

With no annotations, the description carries the full burden and does well: it discloses the endpoint called, that the response is a 'sanitized subset', the exact set of team-membership fields exposed, and which sensitive fields (email, API keys, signatures, preferences) are deliberately omitted. It omits auth requirements and pagination/caching behavior, 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?

Two sentences, front-loaded with the outcome and then the field-level detail. The field enumeration is long but is the substantive content rather than padding, so it earns its place; a minor trim is conceivable.

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?

An output schema exists, so the description need not fully explain return values, yet the field list usefully complements it by explaining what is intentionally excluded (sanitization), which the schema alone would not convey. For a no-argument, no-annotation read tool this 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly does not invent argument semantics, and instead documents the shape of what is retrieved.

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 and resource ('Return ... the current user's capabilities and team roles') and even cites the underlying endpoint /users/me, so the purpose is unmistakable. It does not explicitly differentiate itself from the adjacent sibling refresh_team_caps, which is the only thing keeping it off 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?

Usage is implied only: the phrase 'relevant for capability detection' hints at when the tool is useful, but there is no explicit when-to-use, when-not-to-use, or comparison to alternatives such as refresh_team_caps. No prerequisites or auth context 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?

No annotations are provided, so the description carries the full burden and does supply the key safety claim ('Read-only') plus the edge payload shape (from {type,id}, to {type,id}, direction label). It is silent on pagination, permission requirements, behavior when the entity has no links, and whether the direction label is derived or stored.

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 the verb and resource, then the direction taxonomy, then the edge shape and read-only flag. No marketing 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?

The description fully covers what the tool does, the direction model, and the return edge structure, so an agent can call it correctly without any additional documentation.

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

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

Schema description coverage is 0% and none of the five parameters are named or explained. The description's incoming/outgoing discussion obliquely maps to include_incoming/include_outgoing, but never mentions the toggle semantics, the boolean defaults, or include_raw at all, and gives only a vague hint ('experiment or item') about valid entity_type values, which have no enum in 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: 'Fetch directed link edges of a single eLabFTW experiment or item', and enumerates the concrete edge collections it reads (items_links/experiments_links vs related_*). The word 'single' plus 'directed link edges' implicitly separates it from network-walking siblings like expand_links_network.

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 rather than stated: the 'single experiment or item' scope bounds the tool, and the incoming/outgoing split tells the agent it can choose edge directions. But it never says when to prefer this over expand_links_network, ensure_link, or get_item, and gives no prerequisites (e.g. entity must exist, which entity_types are valid).

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

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

Annotations are absent, so the description carries the full behavioral burden, and it does well on the key trait: 'Always safe to call; never writes anything' explicitly declares read-only safety. It also enumerates the returned contents. It omits auth/permission or not-found behavior, keeping it below 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?

Three short sentences, front-loaded with the operation and identifier, then the return payload, then the safety note. Every sentence earns its place with no redundancy.

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

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

For a simple single-entity read with an output schema already documenting the return shape, the description supplies enough: what it fetches, how it is identified, and the read-only safety profile. 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 coverage is 0% and the single parameter ('Id', integer) is described only mechanically, so the schema does not compensate. The description supplies the meaning — 'numeric ID' identifying the experiment to fetch — which resolves the otherwise undocumented parameter.

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

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

States a specific verb (fetch), resource (elabFTW experiment), and scope (single, by numeric ID). The word 'single' cleanly separates it from the list_experiments sibling without the schema being opened.

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 'fetch a single experiment by its numeric ID', so an agent knows to use it when it already has an ID. However, no explicit when-to-use/when-not guidance is given, and no alternatives (e.g. list_experiments for discovery) 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?

With no annotations, the description carries the full burden and does disclose the key safety trait ('Always safe to call; never writes anything') plus the shape of the result (full record with body, metadata, steps). It stops short of noting anything about auth requirements or error behavior for a missing/invalid ID, so it is strong but not exhaustive.

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, each doing distinct work: what it fetches, what it returns, and how it relates to alternatives. Front-loaded with the purpose and free of filler.

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

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

An output schema exists, so return values need no elaboration, and the description still sketches the record contents. For a one-parameter read tool with sibling routing spelled out, 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 coverage is 0% and the single property is a bare integer titled 'Id', so the description must compensate. It does by specifying 'numeric ID' and implying it identifies an existing template, which is more than the schema conveys, though it adds no format constraints or failure modes.

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 (Fetch) plus resource (elabFTW experiment template) and scoping detail (single, by numeric ID). It also explicitly distinguishes itself from list_experiment_templates and create_experiment_from_template, so an agent can tell it apart from siblings 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?

Names the two relevant alternatives and the condition that selects each: list_experiment_templates to discover IDs, create_experiment_from_template to instantiate one. This leaves nothing to inference about when to use this tool versus its neighbors.

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 no annotations, the description carries the behavioral burden and does disclose the key trait: 'Always safe to call; never writes anything,' plus the returned payload (metadata, tags, comments, links, uploads). It does not cover permissions, rate limits, or behavior when the ID is not found, which keeps it 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?

Three tight sentences, front-loaded with purpose, then return contents, then safety. No filler and nothing 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?

Because an output schema exists, return-shape explanation is not required, yet the description still names the returned fields helpfully. For a single-parameter read tool with no annotations this is nearly complete, with only not-found/permission edge cases 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 coverage is 0% and the single 'id' property has only a type. The description compensates by specifying the ID is numeric and identifies the entity class it addresses, giving the agent enough to construct a valid call.

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 (Fetch), resource (single elabFTW database item / resource), and scope (by its numeric ID). This clearly distinguishes it from list_items and from get_experiment/get_item_type siblings that target different resource types.

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: an agent infers it should be used when it already has an item ID. There is no explicit when-to-use, no contrast with list_items (fetch many) or resolve_entity_by_query, and no stated prerequisite. The sentence about safety addresses behavior, not selection.

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?

No annotations are provided, so the description carries the burden, and it does disclose the safety profile ("Always safe to call; never writes anything") plus the shape of the returned record. It omits error behavior for an invalid or missing ID and any permission requirements, leaving modest gaps.

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 sentences with no filler, leading with the action and ID requirement. The sentence enumerating return fields is somewhat redundant given an output schema exists, costing a little efficiency.

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 an output schema, the agent gets purpose, discovery path, and safety in one place. Missing only edge-case guidance (invalid ID handling), which is a minor rather than a blocking 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 0%, so the schema's bare "Id" integer is all the structured data offers. The description adds that it is the item type's *numeric* ID and hints where IDs come from (list_item_types), but gives no constraints, range, or failure modes for the value.

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

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

States a specific verb and resource ("Fetch a single elabFTW item type by its numeric ID") and the word "single" implicitly contrasts with the list sibling. It does not address the nearby get_item sibling, so full sibling differentiation is not achieved.

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?

"Use list_item_types to discover item types" names the alternative and the condition that selects it, giving the agent a clear routing path. It stops short of stating explicitly when this tool (versus that one) is the right call, so it is clear context rather than a full when/when-not rule.

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 no annotations, the description carries the full burden and discharges it by declaring 'Always safe to call; never writes anything', which conveys the read-only safety profile. It also discloses the returned fields, though it leaves pagination/rate behavior unstated.

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 purpose then the parameter, return fields, and safety note. Each sentence earns its place with no redundancy.

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

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

For a simple single-parameter list tool, the description covers purpose, parameter behavior, returned fields, and safety, and the presence of an output schema means return structure need not be elaborated further. 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 0%, so the description must compensate, and it does: it explains that team_id defaults to 'current' and otherwise accepts a numeric team ID. This fully documents the single parameter, though it adds no format validation detail.

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

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

The description gives a precise verb+resource ('List all experiment categories') scoped to the 'active elabFTW team', which distinguishes it from the adjacent 'list_item_categories' sibling. An agent can identify the tool 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?

It gives clear context for how the output is consumed ('use those ids when filtering list_experiments by category') and explains the team_id default. It does not explicitly exclude alternatives like list_item_categories, but the retrieval context is well established.

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?

No annotations are provided, so the description carries the full burden, and it does state the safety profile explicitly ('Always safe to call; never writes anything'). It also describes the return shape and the pagination detection rule (returned_count vs limit), which is real behavioral context beyond the schema. It stops short of noting auth/permission requirements or rate 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?

Four short sentences, front-loaded with purpose and returning shape, then the filter rule and the safety note. Nothing is redundant, though the pagination instruction is slightly operational detail 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?

An output schema exists, so return values need not be explained, and the description covers safety and pagination adequately. The significant remaining hole is that over half the input parameters have no semantic documentation anywhere, which an agent would need 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 0%, so the description must compensate, and it only partially does: it names q, tags, and the category/user/status ID filters. Sort, limit, order, scope, state, and offset are left entirely undocumented in both description and schema, which is a meaningful gap for an 11-parameter tool.

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

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

The description opens with a specific verb and resource ('Search or list elabFTW experiments'), which is unambiguous. It does not explicitly differentiate from sibling list tools such as list_items or list_experiment_templates, so an agent must infer the distinction from the resource name 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?

It gives one concrete routing rule — use dedicated filter arguments for known category/user/status IDs or tags rather than q — which is genuinely useful. However, it offers no guidance on when to choose this tool over alternatives like get_experiment or list_items, leaving the primary selection decision 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?

No annotations are supplied, so the description carries the full burden, and it does disclose the critical trait: "Read-only." It says nothing about pagination, result caps, or whether the team must exist/have permissions, so it is adequate but not rich for an annotation-free 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 with zero waste; the purpose is front-loaded and the parameter rule follows immediately. Nothing could be removed without losing 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?

An output schema exists, so return-value shape need not be described, and the single parameter and its default are covered. Only minor gaps remain (pagination, team-permission preconditions).

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

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

Schema description coverage is 0%, so the description must compensate, and it does: team_id accepts 'current' (the default) or a numeric team ID. That is exactly the semantic an agent needs and the schema leaves bare.

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 ("List all experiment statuses") and scopes it to the active eLabFTW team. It does not explicitly distinguish itself from the near-named sibling list_item_statuses, but the resource is unambiguous.

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

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

Usage is implied — an agent that needs the set of experiment statuses would call this — and the default team behavior is clarified. There is no explicit when-not guidance or routing to alternatives such as list_item_statuses.

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 no annotations, the description carries the safety burden and does so ('Always safe to call; never writes anything'), and notes the paged structured response. It stops short of richer behavioral detail (auth scope, pagination boundaries with offset/limit), so it is strong but not complete.

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

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

Four tight sentences, each earning its place: identity, return shape, sibling disambiguation, and routing. Nothing is padded and the disambiguation is front-loaded.

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

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

An output schema exists, so return values need no prose, and the read-only nature is stated. The remaining hole is the fully undocumented filtering/paging parameter set, which leaves an agent guessing at how to narrow results.

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?

Seven parameters (q, sort, tags, limit, order, state, offset) have 0% schema description coverage, and the description never explains any of them — notably 'state', which is ambiguous, and how sort/order interact. The description does not compensate for the coverage gap.

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

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

States a specific verb+resource ('List elabFTW experiment templates') and immediately disambiguates from the closest confusing sibling by asserting templates are 'DIFFERENT from item types (use list_item_types for those).' An agent can select this 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 routes to alternatives by intent: list_item_types for item types, get_experiment_template for a single record, create_experiment_from_template for consuming one. It also states the safe-to-call condition, so both when-to-use and when-to-use-something-else 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?

No annotations are provided, so the description carries the full load, and it does disclose the safety profile ('Always safe to call; never writes anything') plus the team-scoping behavior. It omits permission/authorization requirements and pagination or ordering behavior for the returned list.

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?

Four short clauses, each earning its place: identity, parameter rules, downstream use, and safety. The core purpose is front-loaded 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?

An output schema exists, so return values needn't be explained, and the description covers scope, the lone parameter, and safety. For a simple one-param list tool nothing an agent needs 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 0% and the single team_id param has no schema description, so the description must compensate — which it does by stating the default ('current') and the accepted numeric team ID format. It doesn't say where numeric team IDs come from or whether a stringified number is required.

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

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

Specific verb+resource ('List all item categories') with a clarifying synonym ('resource categories') that separates it from the sibling list_experiment_categories. It never explicitly contrasts with list_item_types, so an agent still has to infer that boundary.

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 concrete downstream use case ('Use the returned ids when filtering list_items by category') and explains the team scoping choice, which is clear context for when to reach for this tool. It stops short of stating when-not or naming an alternative sibling.

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

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

With no annotations, the description carries the full burden and does disclose the key safety trait: 'Always safe to call; never writes anything.' It also reveals the return shape (paging metadata, applied filters, records) and how to detect more pages. It omits auth/permission requirements, but for a read-only list tool this is solid disclosure.

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?

Four tight sentences, front-loaded with purpose then return/paging advice then parameter guidance. No filler, though 'Search or list' hedges where one precise verb would be cleaner.

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?

An output schema exists, so return values need not be restated, and the description thoughtfully covers paging. But for an 11-parameter tool with 0% schema documentation and no annotations, the description leaves too many filter parameters unexplained to be considered complete.

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

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

Schema description coverage is 0% across 11 parameters, so the description must compensate and largely does not. It only alludes to q and to 'dedicated filter arguments for known IDs or tags'; scope, state, sort, order, limit, and offset are never explained in prose or 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: 'Search or list elabFTW database items (resources)', which separates it from list_experiments and list_item_types by naming the resource type. The duality of 'search or list' is slightly muddy but an agent can still identify this as the general item-listing 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?

Offers parameter-level guidance ('Use the dedicated filter arguments for known IDs or tags instead of q'), which is useful. However, it never says when to prefer this tool over get_item or resolve_entity_by_query, so broader routing 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?

No annotations are provided, so the description carries the full burden. It does usefully declare "Read-only," which covers the safety profile that annotations would normally supply, but says nothing about pagination, permissions, or what happens when an unknown team_id is passed.

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 what is listed and scoped by team, followed by the accepted argument values. Every clause earns its place with no filler.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose plus the sole parameter's semantics. The only omission is any hint about access requirements or pagination/size limits for a team-wide listing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains that team_id accepts 'current' (the default) or a numeric team ID. It does not state what a numeric ID resolves to or error behavior for invalid IDs, but the accepted-value semantics are covered.

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

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

The description names a specific verb ("List") and resource ("item statuses (resource statuses)") scoped to the active eLabFTW team, so an agent knows exactly what it returns. It is clear but does not explicitly distinguish itself from near-siblings such as list_experiment_statuses or list_item_types.

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 text: call it to enumerate the team's statuses, with the team_id scoping rule given. There is no explicit when-to-use/when-not-to-use guidance and no mention of the alternative status/type listing tools, so the agent must infer the boundary.

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

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

With no annotations, the description carries full behavioral burden and does disclose read-only safety ('Always safe to call; never writes anything') plus what item types conceptually represent. It omits any pagination or default-limit behavior despite limit/offset parameters.

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; the core purpose is front-loaded before the disambiguation and safety notes.

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?

Because an output schema exists, return values need no explanation, and purpose, alternatives, and safety are all covered. The one real gap is that none of the 7 filter/pagination parameters are described anywhere.

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

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

Schema description coverage is 0% across 7 parameters, so the description must compensate, but it explains none of them. The meaning of q (full-text?), sort, order, state, tags, limit (default 25) and offset is left entirely undocumented.

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

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

The description states a specific verb and resource ('List elabFTW item types'), gives the alternate name ('resource categories') and the API path, and explicitly distinguishes itself from experiment templates and get_item_type. An agent can identify exactly what this returns without opening another 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?

It names the alternative (list_experiment_templates) and the condition that selects it, and routes single-item lookups to get_item_type. When-to-use and when-not-to-use are both explicit.

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

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

With no annotations provided, the description carries the full burden and does well: it explicitly declares 'Read-only' and describes the concrete response shape (entity_type, entity_id, total_steps, steps array with id/body/finished/ordering/deadline). It stops short of stating pagination behavior, ordering guarantees, auth/permission requirements, or behavior when the entity has no steps.

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 front-loaded sentences: purpose/scope first, then return shape, then the render_markdown branch. Every sentence is load-bearing, though the return-field enumeration is somewhat redundant given an output schema exists.

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

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

For a simple read-only listing tool with an output schema and no annotations, the description is nearly sufficient: it covers scope, the render_markdown toggle, and the read-only guarantee. Remaining gaps are minor — no pagination limits, no behavior for zero steps, and the return-field detail is partly duplicated by the 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 description coverage is 0%, so the description must compensate, and it partially does: it enumerates the valid entity_type values and explains that render_markdown=True adds a 'markdown' field with a GFM checkbox list and deep links. It does not clarify what 'id' refers to beyond the entity type, nor the default behavior of render_markdown (the schema does supply default=false).

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 ('List all steps (tasks) attached to an eLabFTW experiment, item, experiment template or item type') and enumerates the exact valid entity scopes. An agent can distinguish it from mutation siblings like add_step/update_step/toggle_step/delete_step 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?

Usage is implied by the verb 'List' and the 'Read-only' tag, and the entity_type list tells the agent which entities are in scope. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives (e.g., use add_step to create, toggle_step to flip completion).

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 no annotations, the description carries the full burden and does reasonably well: it discloses the side effect (updates the cache), the read/write boundary ('Does not write to eLabFTW resources'), and that returned capability fields are sanitized for policy checks. It stops short of stating auth/permission prerequisites or failure 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?

Three tight sentences: purpose first, then the mechanism, then the non-mutation disclaimer last. Nothing is padded, though the mechanism sentence could be slightly tighter given an output schema already exists.

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?

Zero parameters and an output schema mean the return shape needn't be re-explained, and the description still summarizes the returned sanitized team_caps object. What remains unaddressed is the relationship to the sibling capability tool and any permission requirements, but nothing essential to invoking it is missing.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to clarify argument usage, and it does not introduce any spurious parameter-like claims.

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 ('Refresh and return the cached team capability flags') and adds the mechanism (fetch team record, sanitize, update cache). It is clearly distinguishable in intent from get_current_user_capabilities, but never names that sibling explicitly, so differentiation is left 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?

The phrase 'for the current session' and 'cached' implies usage when the session cache needs refreshing, but there is no explicit when-to-use, when-not-to-use, or call-out to get_current_user_capabilities as the alternative. Usage is implied rather than 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?

With no annotations, the description carries the full burden and does disclose read-only, always-available semantics plus the resolution states (not_found | unique | ambiguous). It does not cover permission requirements, rate limits, or whether tag/filter args broaden or narrow results, leaving a modest 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?

Two compact sentences, front-loaded with the action and the return contract. No filler, though the second sentence packs a few concepts without fully unpacking them.

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?

An output schema exists, so return values need not be explained, and the resolution semantics are a useful bonus. But for a 10-parameter tool with zero schema descriptions, the description is not complete enough to guide 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?

Ten parameters at 0% schema description coverage, and the description only gestures at a free-text query and an entity type. Nine parameters (tags, scope, offset, extended, owner_ids, status_ids, category_ids, limit_candidates) are undocumented in both schema and description, so an agent must guess their meaning and interactions.

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 (search experiments or items by query) and the output shape (compact candidates for disambiguation), which separates it from the list_* siblings that return full entities. It does not name any sibling explicitly, so it lands at 4 rather than 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?

"Use it to find an id before acting on it" gives a clear use context and positions the tool as a precursor to mutation tools. No explicit when-not or named alternatives are given, but the workflow guidance is concrete.

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 no annotations, the description carries the full burden and does well: it discloses that the operation is read-only ('writes nothing') and that it depends on an AI endpoint, with a defined fallback placeholder behavior. It does not cover auth requirements or rate limits, but the core behavioral profile is clear.

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 purpose followed by the safety and dependency caveats. 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?

An output schema exists so return values need not be explained, and the description covers the primary operational caveat (AI endpoint dependency). For a single-parameter read-only tool this is nearly complete, with only minor gaps around the id 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 coverage is 0% and the sole 'id' parameter is undocumented in the schema. The description implicitly clarifies that the id refers to an eLabFTW experiment, adding marginal meaning, but does not specify format or behavior 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?

States a specific verb (Generate) and resource (AI review summary for an eLabFTW experiment) and even enumerates the output components (documentation quality, risks, suggestions, completeness score). This clearly distinguishes it from read-only siblings like get_experiment and from the related add_ai_review_comment.

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 a key prerequisite ('Needs an AI endpoint; without one the response carries the upstream placeholder marker'), which tells the agent when the tool is useful. However, it never explicitly contrasts this with alternatives such as get_experiment or add_ai_review_comment, leaving the choice 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?

With no annotations provided, the description carries the behavioral burden and does so by explicitly declaring 'Read-only — writes nothing'. It also discloses the follow-up persistence path via 'update_entity_metadata'. It does not cover auth requirements or whether the target entity must already exist, but the key safety trait is clearly stated.

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 action and scope, followed by the critical read-only and persistence guidance. 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?

An output schema exists so return values need not be described, and the read-only nature plus the persistence sibling are covered. The remaining gap is the lack of any parameter explanation, which is a real but bounded omission for a two-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate for the two undocumented parameters. While 'experiment or item' loosely hints at the 'entity_type' values, neither 'entity_type' nor 'id' is explained with format, allowed values, or meaning.

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

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

The description states a specific verb and resource ('Suggest structured metadata (custom fields) for an eLabFTW experiment or item') and immediately names the persisting sibling 'update_entity_metadata'. An agent can distinguish this read-only suggestion tool from the write tool without inspecting 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?

It clearly describes the intended workflow: use this to generate suggestions, then feed the result into 'update_entity_metadata' to persist. It does not state explicit exclusions versus sibling tools like 'suggest_tags', but the context of use 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?

With no annotations, the description carries the full burden and does disclose the key behavioral trait: it is read-only and writes nothing, which is the critical distinction from apply_tag_suggestions. It does not cover auth requirements or whether suggestions are persisted in any session state, leaving some gaps.

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 the core action front-loaded and the read-only constraint plus the persistence alternative immediately following. No wasted words.

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

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

An output schema exists, so return values need not be described, and the read-only nature and persistence path are covered. The main remaining hole is the undocumented parameters, which the description does not compensate for.

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

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

Schema description coverage is 0% for two required parameters, and the description only loosely implies entity_type by mentioning 'experiment or item'. It adds no meaning for id or the accepted entity_type values/format, so the agent gets little guidance beyond the bare schema.

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

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

States a specific verb (suggest) and resource (tags) scoped to experiments or items, and notes suggestions are content-based. It also names the differing sibling apply_tag_suggestions, so an agent can separate the suggestion step from the persistence step without inspecting 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?

Clearly routes the agent: use this to generate suggestions, then use apply_tag_suggestions to persist them. This gives a clear use context and names the follow-on alternative, though it does not state explicit exclusions or preconditions (e.g., required permissions).

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 no annotations, the description carries the full burden and does well: it explicitly labels this a WRITE OPERATION and names the required step write scope, plus discloses the non-obvious toggle behavior when finished is omitted. It does not cover idempotency or what the response contains, but an output schema exists to cover 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?

Three short sentences with zero filler. The write-operation warning is front-loaded and the flag semantics follow immediately, so the most decision-relevant information lands first.

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

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

Output schema exists, so return values need not be described. The description covers the mutation, the auth scope, and the toggle semantics, but leaves 'entity_type' and the id/step_id relationship undefined, and gives no disambiguation against the adjacent step-mutation siblings.

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

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

Schema description coverage is 0% for 4 parameters, so the description must compensate. It fully explains the crux parameter 'finished' (1=complete, 0=incomplete, omitted=flip), but says nothing about 'entity_type' (an unconstrained required string with no enum) or the distinction between 'id' and 'step_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?

States a specific verb and resource ('Mark a step as complete or incomplete'), so the action is unambiguous. However, it does not distinguish itself from the sibling 'update_step', which plausibly could also change completion state, so an agent must still guess which 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?

The description explains the semantics of the finished flag including the omitted case (server flips current state), which is real usage guidance. But it gives no when-to-use vs when-not-to-use framing against 'update_step' or 'add_step', and no prerequisites beyond the scope note.

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 no annotations, the description carries the full burden and does well: it flags a WRITE OPERATION, the required write scope, and the at-least-one-field constraint. It stops short of saying whether unspecified fields are left untouched or that the read-back is the verification mechanism's output.

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

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

Three tight sentences, front-loaded with the purpose and then the operational caveats. No filler; each sentence adds 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?

An output schema exists, so return details needn't be spelled out, and the write scope plus validation rule are covered. The main gap is that entity_type and id are undocumented and the valid values for entity_type (experiment vs item) are 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 0% across 6 params. The description covers title, status_id, and category_id (including that at least one is required), but leaves id, entity_type, and trace_id unexplained — notably entity_type, which likely drives behavior. Partial compensation, so a mid score.

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 (update), the exact resource and scope (top-level scalar fields on an existing eLabFTW experiment or item), and enumerates the affected fields. This clearly separates it from siblings like update_entity_metadata and update_experiment_body.

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 precondition ('at least one of title, status_id, category_id must be given') and the required permission scope. It does not explicitly name alternatives for editing non-scalar fields, but 'top-level scalar fields' implicitly positions it against update_entity_metadata.

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 no annotations, the description carries the full burden and largely meets it: it discloses the write nature, the required write scope, the destructive semantics of mode='overwrite' ('rebuilds it'), the preservation semantics of 'merge', and a read-back verification. It omits edge behavior such as what happens to fields not mentioned in a merge or any rate 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?

Front-loaded with the purpose and the WRITE OPERATION/scope warning, then parameter detail. The 'fields' schema description is dense but every element earns its place; no filler sentences.

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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes the read-back verification. Combined with the write-scope note and mode semantics, this is nearly complete for a 6-param write tool; only the trace_id parameter and merge edge cases are 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 0%, so the description must compensate, and it does for the complex parameters — it gives the JSON shape of 'fields' ({key, value | values, type, group_id, allow_multi_values, description}), the structure of 'groups' ([{id, name}]), and the default/values of 'mode'. The simple params (id, entity_type) are self-evident, but 'trace_id' is left undocumented.

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

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

States a specific verb ('Update') and resource ('metadata (custom fields)') and enumerates the four entity types it applies to, so the agent knows what it targets. It does not differentiate itself from the sibling 'update_entity_fields', which sounds like a near-identical operation, leaving a routing ambiguity.

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

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

The description explains the merge vs overwrite modes and flags 'WRITE OPERATION — requires the update write scope', which is useful operational guidance. However, it never states when to choose this tool over the sibling 'update_entity_fields', so the agent must infer the distinction.

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 no annotations, the description carries the full burden and does so richly: it declares the write operation and required update scope, states that content_type is preserved, specifies that append keeps the original body byte-for-byte, details overwrite prerequisites (allow_body_overwrite config plus confirm_overwrite=true), and notes read-back verification.

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 WRITE OPERATION warning, then proceeds in tight, information-dense sentences. Every clause (scope, content_type preservation, mode semantics, overwrite preconditions, verification) earns its place with no filler.

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

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

For a mutation tool with no annotations and an output schema present, the description covers the safety profile, preconditions, and mutation semantics an agent needs. Return-value detail is rightly deferred to the output schema, and the read-back verification note ties it together.

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

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

Schema description coverage is 0%, so the description must compensate; it explains mode semantics and its default and the confirm_overwrite coupling well. id and text are self-evident from their names, but trace_id is left unexplained, keeping this from a 5.

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

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

States a specific verb and resource ('Update the body of an existing eLabFTW experiment'), and the 'experiment' scoping plus body target distinguishes it from the sibling update_item_body. An agent can identify the target object and mutation 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 operating context: it is a write operation requiring the update write scope, and it lays out append (default) vs overwrite conditions including the required config flag and confirm_overwrite. It stops short of explicitly routing the agent to sibling alternatives, so it is a 4 rather than 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 no annotations, the description carries the full burden and does well: it flags the WRITE OPERATION, names the required update write scope, and spells out which mode destroys the original body and what confirmation is needed. It omits details like reversibility of append vs overwrite beyond the stated replacement semantics, 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?

Two tight sentences that front-load the operation and the destructive-path warning; 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?

Output schema exists, so return values need not be explained, and the description covers the scope and destructive-mode requirements well. The gap is undocumented semantics for id/text/trace_id on a mutation tool with zero schema descriptions.

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

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

Schema description coverage is 0%, so the description must compensate. It explains mode and confirm_overwrite semantics, but the required id and text parameters and trace_id are left entirely undocumented in both schema and description; it also mentions allow_body_overwrite, which is not a parameter of this schema, adding ambiguity.

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 ('Update the body of an existing eLabFTW database item'), which cleanly distinguishes it from siblings like update_experiment_body and update_entity_metadata.

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 conditional guidance for the two modes, including the default ('append' preserves and appends) and the conditions for the destructive path (allow_body_overwrite plus confirm_overwrite=true). It does not name sibling alternatives for when this tool is the wrong choice, 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.

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

With no annotations, the description carries the full burden and does unusually well: it flags the WRITE OPERATION, the required write scope, the at-least-one-field constraint, and discloses that deadline_notif may be rejected by the API and reported as unsupported. What it omits is whether unspecified fields are preserved and what the response/error shape looks like, which keeps it below 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-loaded and tight: the mutation and its scope constraint come first, with no padding sentences. The trailing '(see notes)' points at notes that are not present anywhere in the provided material, a small dangling reference that costs a point.

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 existence of an output schema means return values need not be explained, and the write-scope plus field constraint are covered. But for a no-annotation mutation tool, the unresolved identifier semantics and the dangling '(see notes)' reference leave the agent guessing about entity_type/step_id usage.

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

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

Schema description coverage is 0%, so the description must compensate, and it only explains half the parameters (body, deadline, deadline_notif). The three required identifiers (id, step_id, entity_type) remain completely undocumented in both schema and description, which is a meaningful gap for a tool that cannot be called without them.

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 ('Update an existing step') and names the editable fields (body, deadline). It implicitly separates itself from add_step/delete_step/toggle_step by scoping to field edits, though it never explicitly contrasts with toggle_step, which an agent might confuse for a status change on the same resource.

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 real precondition ('at least one of body, deadline, deadline_notif must be provided') and names the required write scope, which is genuinely useful. However, it never states when to reach for this tool versus toggle_step, add_step, or update_entity_fields, so alternative selection 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?

With no annotations, the description carries the full behavioral burden and discharges much of it: it discloses the write/auth requirement (update scope), the validation constraint (allowed mime types), and the return contents (upload id and size). Gaps remain around size limits, idempotency, and permitted entity_type values, keeping it out of the top band.

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?

Four short sentences, each earning its place: purpose, auth/operation class, accepted formats, and return. The most decision-relevant facts (what it does and that it is a write) are front-loaded 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?

An output schema exists so the return format need not be spelled out, and the auth/mime facts are supplied. However, for a 6-parameter write tool with zero schema descriptions and no annotations, the unexplained parameter semantics and missing accepted entity_type values leave real gaps for an agent trying to invoke it correctly.

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

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

Schema coverage is 0% across 6 parameters, so the description must compensate but largely does not. It loosely hints at entity_type ('experiment or item') and content_base64 ('from base64-encoded content'), while filename, mime_type, and comment are never explained and no accepted entity_type values are given.

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 (upload), resource (a single image attachment), target (eLabFTW experiment or item) and source (base64-encoded content) are all stated. No sibling tool performs uploads, so an agent can immediately place it. The purpose is self-contained and unambiguous.

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

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

It states the operation class (WRITE OPERATION), the required scope (update write scope), and the accepted input types (png/jpeg/gif/tiff), which are effective gating conditions. It stops short of explicitly naming a when-not or an alternative, but no sibling offers a competing path, so little is left ambiguous.

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