Aevia

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive/closed-world), yet the description still adds substantial behavior: the default two-sided summary with top-20-per-side ordering, grouping by unit, largest-amount-first, true totals in headings, follow-up hints when rows remain, and paging semantics for section+offset. This is well beyond what structured fields convey.

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

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

One dense paragraph, but it is front-loaded with the purpose and ref-prefix legend before the paging and edge-case detail. Almost every sentence carries operational content; a mild deduction for length and for re-covering limit/section behavior already present in the schema.

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

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

With no output schema, the description must describe returns, and it does — default summary composition, pagination, totals, and hints. For a read-only lookup with 6 params, nothing an agent needs to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks — notably what each ref prefix resolves to (p=process, e=product system, f=flow, m=LCIA method) and that process exchange rows carry f<N> refs usable by compose/edit tools. It largely restates limit/offset/include_providers behavior that the schema already documents.

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

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

Opens with a specific verb+resource ('Detail for one engine-catalog object by ref') and immediately decodes the four ref prefixes (p/e/f/m). It explicitly separates itself from siblings: refs come from engine_search, and workspace s<N> objects belong to lca_get, not this 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?

States the prerequisite (run engine_search first for a ref), the exclusion (rejects s<N>, use lca_get instead), and per-type usage guidance (section='factors' is 'rarely needed'; include_providers only applies to flow refs). An agent can route correctly without opening any schema.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds non-obvious behavioral context the annotations cannot: refs are session-scoped, refs minted via `scope_ref` stay bound to that database, results come back as one page of `limit` plus the true total, and unmatched queries fall back to labelled partial matches.

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

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

Purpose and the core enumeration trick are front-loaded, and there is little filler, but the whole definition is one dense unbroken block covering query, kind, flow_type, process_type, engine and scope_ref in sequence, which makes it harder to scan than it needs to be.

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

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

With no output schema, the description carries the return-value burden and does: it explains that hits are typed refs (`p1`, `e1`, `f1`), that a system hit is an `e<N>` engine-catalog ref rather than a workspace `s<N>`, and that results are paginated with a true total. Pagination is also covered by the limit/offset schema fields, so nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining matching semantics the schema only gestures at (word-by-word against names/categories/location codes, no semantic matching, concrete `polypropylene injection moulding` example) and by clarifying cross-parameter interactions the schema lists separately (flow_type only with kind='flow', scope_ref overrides engine).

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 first sentence gives a specific verb and resource ('Search an LCA database for processes, systems, flows or methods') and the rest of the description positions it against engine_get (fetch by ref) and lca_run_assessment (consume refs), so the agent can tell what this tool is for without opening the schema. The scope of what is searchable and what refs are minted is stated up front.

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?

Rich when-to-use guidance: `query='*'` to enumerate a kind, `scope_ref` specifically 'for comparing across databases', `flow_type` only with kind='flow', `process_type` only with kind='process'. What is missing is an explicit statement of when NOT to use it (e.g. use `engine_get` when you already hold a ref), though the ref handoff is implied.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the library is English-language so technical terms/scientific names match best, a multi-journal fragment is rejected with candidates rather than guessed, omitting journal widens scope to uploads and journal-less documents, and filters are inert in document_refs mode. Return shape (abstract + chunks) is also sketched.

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

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

Front-loaded with the core action, then a tight numbered enumeration of the three modes, then the input requirement and the filter-scoping caveat. Every sentence earns its place and the parenthetical constraints are load-bearing rather than filler.

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

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

With 7 parameters, no required params, and no output schema, the description does the important work of explaining mode interactions and mutual constraints, which is what an agent needs to call it correctly. It could say a bit more about what a returned excerpt/chunk actually contains (ordering, sizing) and about behavior when a ref is invalid, but the essentials are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: the trade-off of omitting journal (includes the user's own uploads), the fragment-resolution/rejection behavior, and the interaction where scope filters are ignored once document_refs are given. It does not add anything for limit/top_k_chunks_per_doc or the year bounds, which the schema already handles.

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 concrete verb+resource ('Search the library and return abstracts with matching passages') and enumerates three operating modes keyed on which inputs are supplied. It is very clear about what the tool produces, but it never names sibling tools (knowledge_search, knowledge_get_full_document), so differentiation from them is only implied by the 'discover AND return excerpts in one call' framing.

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?

Strong mode-selection guidance: query-only for discovery+excerpts, document_refs-only for a table-of-contents glimpse, both for re-ranking scoped to refs, plus the hard constraint that at least one of query/document_refs is required. It also states when metadata filters are ignored. It stops short of naming an alternative tool for pure document discovery (e.g. knowledge_search), which would be the 5-level signal.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds real behavioral context: [ref-only] documents return only an abstract rather than failing or returning empty. It could go further on size/truncation behavior for large full texts, hence 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?

Four tight sentences, front-loaded with what the tool returns and the ref contract, then the sibling comparison and the edge case. No padding or repetition.

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

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

With no output schema, the description still tells the agent what comes back (full text, or the same abstract as excerpts for ref-only entries) and where the input ref originates. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents the k<N> format and the rejection of titles/DOIs/uuids. The description restates the ref origin ('comes from a recent knowledge_search') without adding format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Full text of one library document') and scopes it precisely by ref type. It explicitly contrasts itself with knowledge_get_excerpts and knowledge_search, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives an explicit when-to-use-this-vs-alternative rule: excerpts 'usually suffice', this tool is for the whole paper, and it names which refs are even eligible ([ref-only] excluded). That is a genuine routing decision, not vague context.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description adds substantial context beyond them: returns are metadata-only with no abstracts or excerpts, refs persist only for the session, coverage is English-language and abstract-heavy, and journal-fragment ambiguity is rejected with candidates rather than guessed. This is genuinely useful behavioral 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?

Front-loaded with corpus and scope, then returns, then ref lifecycle and downstream tools, then parameters — every sentence carries distinct information despite the density. No filler or redundancy.

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

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

With no output schema, the description carries the return-value burden and does so precisely (ref-numbered title/authors/year/journal/DOI only), plus session-scoped ref persistence. For a 5-parameter, read-only search tool this is 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 coverage is 100%, so the baseline is 3, and the description earns an increment by tying parameters to intent: limit default 12 with 'a larger limit suits broad literature surveys', year_from/year_to as optional bounds, and journal as a full-name single-journal restriction. Most of this restates the schema, so it does not reach 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 (search) and resource (130,000+ peer-reviewed sustainability papers plus account uploads), scopes the corpus by journal and date, and implicitly distinguishes itself from the sibling retrieval tools it hands refs to. An agent can tell this apart from knowledge_get_excerpts and knowledge_get_full_document without opening a 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 names the downstream alternatives — refs are 'accepted by knowledge_get_excerpts (passages) and knowledge_get_full_document (the full paper)' — and the journal filter guidance states when to omit it and why (it would exclude uploads and unjournaled docs). Conditions for larger limits and per-journal comparison searches are also given.

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

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

Annotations declare a non-read-only, non-idempotent operation but say nothing about cost or side effects; the description fills that gap by disclosing that the first call per solve prepares the engine in the background (~3–5 s) and later calls reuse it, plus the 422 failure modes. It also notes the returned b<N> is a new object separate from the analysed a<N>. Rich disclosure beyond annotations.

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

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

Dense but front-loaded: the core purpose, the ref scheme, and mode behavior come first, with latency and error caveats at the end. Backtick refs compact a lot into one paragraph, though the density borders on cryptic for a first-time reader.

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 11-parameter tool with no output schema, the description explains the return shape (b<N> breakdown ref, p<N>/f<N> row refs for further detail), all mode-dependent parameter applicability, engine-preparation latency, and error conditions. Nothing essential for a 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 100%, so baseline is 3, but the description adds real meaning: `ref` `a<N>` vs `s<N>` semantics, that `method`/`amount` only shape an `s<N>` solve, and the per-mode meaning of results (`total_amount` loop-corrected for process, `amount × CF` for flow, supply-chain walk for upstream). Adds value over the schema without fully documenting every param (e.g. depth/top_n/cutoff stay schema-only).

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 (break down what drives an impact category) and immediately disambiguates from siblings by naming the three modes and the b<N> output object distinct from the a<N> input. An agent can distinguish this from lca_analyze_sensitivity or lca_run_assessment 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 explicit when-to-use routing: `a<N>` analyses a saved assessment's setup, `s<N>` analyses a saved system with no prior assessment, and it names lca_get for enumerating refs. It also states when-not (composed systems support only 'process' via `a<N>`; flow/upstream/s<N> return 422). Lacks an explicit comparison to lca_analyze_sensitivity, so 4 rather than 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?

Goes well beyond the annotations, which only declare it mutates and is non-idempotent. The description discloses performance traits ('analysed exactly and instantly', 'one cached contribution solve', 're-solve openLCA param:<name> parameters', 'deferred'), notes id-namespace rules, 422 behaviour on unresolvable ids, mixing restrictions, and that it returns a durable v<N> separate from the analysed a<N>. It doesn't explain permissions or persistence lifetime beyond 'durable', 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?

Dense and front-loaded with the core purpose, then study modes, id forms, and return value. Every clause carries information, though the run-on sentence packing multiple constraints is dense enough to require careful reading.

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?

Covers the complex nested schema (three study modes, overrides, reference_ref vs threshold) and the deferred/instant behavioral split well. No output schema exists, so it notes the return is a durable v<N>, but doesn't describe the result shape (e.g. per-variable swing rows) that an agent might need.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics: which variable id forms are valid per study (member:/driver:/param:/system:amount), that omission defaults to all, and how fragments resolve. It doesn't fully restate every nested field (e.g. category, variation_pct defaults), so it earns a 4 rather than 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: 'Quantify which inputs drive a system's result, and by how much.' It clearly distinguishes itself from siblings like lca_analyze_contributions by framing the output as ranked drivers/swings rather than contribution shares.

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 states 'Pass at most one study (none = default tornado)' and specifies when to use each mode: tornado for ranking swings, sweep for walking one variable, scenarios for named override sets. It also names the constraints (e.g. 'a break-even needs reference_ref or threshold', 'system:amount is NOT valid here (use sweep/scenarios)').

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

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

Goes well beyond the annotations: nothing is recalculated, factors are read from the engine that produced the assessment, results are stored beside unchanged characterized results, re-application refreshes (consistent with idempotentHint), partial category coverage is possible, and it cites the ISO 14044 restriction on public comparative assertions. This is unusually rich behavioral 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?

Front-loads the core action and keeps every sentence substantive, but it is dense with several distinct topics (storage semantics, refresh, partial coverage, ISO caveat) that could be tightened. No filler sentences, so it stays efficient.

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

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

With no output schema, the description carries the burden of explaining what gets produced: normalized/weighted results per category plus a single score, stored alongside unchanged characterized results, with omitted categories named. An agent has everything needed to invoke and interpret the call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: ref is an a<N> in the named workspace, nw_set must match one of the method's sets (exact or unique part), and workspace is mandatory per call because connections are shared. It reinforces and contextualizes the schema rather than merely repeating it.

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 precise verb+resource: applying a normalization/weighting set to a saved assessment. It explicitly distinguishes itself from lca_compare_assessments (which uses nw_set only to compare assessments all carrying the same set), so an agent can route correctly without opening schemas.

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

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

Gives explicit when-to-use conditions: apply to a saved assessment, unknown set names are refused, re-applying refreshes rather than duplicates, and comparison of sets belongs to lca_compare_assessments. Alternatives and preconditions are named, not 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?

Far exceeds the annotations: it discloses two enforced 400-level preconditions (single LCIA method; single product/amount unless function is stated), that allocation/database/provider differences do not fail but return equivalence warnings, that the result is persisted to a named workspace as primary_ref c<N>, that the matrix is unranked and per-category, and that nw_set only adds already-stored scores. This is a write operation (readOnlyHint=false), and the description makes its side effects and failure modes explicit.

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 paragraph is front-loaded with the core action and follows a logical order: what is saved, what a target is, preconditions, non-refused differences, return value, nw_set, skill. It is dense but several clauses paraphrase the schema descriptions, which is mild redundancy.

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

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

With no output schema, the description still names the returned artifact (primary_ref c<N>) and describes the matrix's semantics (unranked, per-category, optional nw_set column). Preconditions, failure modes, and prerequisites are all covered, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, and each parameter already carries a detailed inline description (nw_set's refusal behavior, targets' a<N> pattern and ≥2 requirement, function's quantified-goal guidance, workspace naming rationale). The prose largely restates that same material, adding little syntax or format information the schema does not already provide.

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 ('Save a comparison across 2–8 saved assessments') and immediately distinguishes itself from lca_run_assessment by noting every run already saves one, so no separate save step exists. An agent can tell exactly what this creates and from what inputs.

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 usage conditions: targets must number 2–8, function is required when targets are not the same product at the same amount, and nw_set requires every target to already carry that set (via lca_apply_nw_set). It points to the assessment_interpretation skill, but never contrasts itself with sibling analysis tools such as lca_analyze_contributions or lca_analyze_sensitivity.

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

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

Annotations already declare the write/non-idempotent/non-destructive profile, but the description adds substantial context the annotations cannot: validation against the database before saving, the errors[]/missing_required[]/warnings[] failure contract with 'nothing is saved', the requirement that a corrected call carry the complete system, and the distinction between a tool error (engine unavailable) and an invalid result. Not covered: permissions/auth prerequisites for writing into a workspace.

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

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

Front-loaded with the core action, then validation and failure semantics, then sibling routing. Every sentence is functional, though the block is dense and the member-ref/UUID rule could be tightened.

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 14-parameter, no-output-schema, non-idempotent mutation tool, the description covers construction (inputs vs stages), validation/failure contract, the returned system_ref, dry_run, and sign/unit conventions. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already carries the per-parameter meaning; the description correctly gets baseline 3. It adds a small amount of non-duplicative constraint ('Members are p<N> refs; UUIDs are not accepted', and the inputs-vs-stages exclusivity), but most parameter guidance is repeated from 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?

The first sentence gives a specific verb and resource: 'Build a product system as a bill of quantities of database processes.' It explicitly names the sibling it is not (lca_compose_linked builds explicit supply edges instead), so an agent can route without opening schemas.

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

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

Explicit routing rules: inputs OR stages but not both, with a stated preference for stages when the system spans life-cycle phases; dry_run for validate-only; and lca_run_assessment named as the consumer of system_ref. It even points to the product_system_authoring skill for build order.

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

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

Annotations only declare write/non-idempotent/non-open-world; the description goes much further, disclosing atomicity ('Every member and supply edge is sent in one call', corrected calls must resend the complete system), validation semantics (validated against the DB; on failure nothing is saved and errors[]/missing_required[]/warnings[] are returned), dry_run behavior, that a tool error means the engine is unavailable, that an unreachable member blocks the build, and that the user's own writable engine is required.

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: the core purpose and the 'structure only' scope lead, followed by routing, semantics, and failure behavior. It is long, and the middle sentences about link routing and ref_process_ref sit far from the corresponding schema fields, but for a 14-parameter tool nearly every sentence 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?

No output schema exists, yet the description specifies the return contract: system_ref on success, and errors[]/missing_required[]/warnings[] on invalid input, plus the dry_run envelope. Combined with the validation and permission constraints, 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 100%, so the baseline is 3, but the description adds real meaning beyond it: the waste-routing semantics of consumer_ref/provider_ref, that ref_process_ref must also appear in member_process_refs, that target_unit_ref is a unit name and not a ref (f/p/s refs rejected), and that p<N>/f<N> refs are required with UUIDs not accepted.

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 ('Build a product system as an explicit process network with supply edges') and immediately scopes it ('Structure only; no LCIA runs'). It differentiates from the sibling lca_compose_assembly by naming it and the condition that selects it.

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

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

Explicitly routes the agent: use lca_compose_assembly for a flat list of materials/quantities, and lca_run_assessment to run LCIA on the returned system_ref. It also points to the product_system_authoring skill. It does not, however, address when to use this versus lca_edit_linked for modifying an existing system.

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

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

Annotations only cover the safety profile (non-read-only, non-idempotent, non-destructive). The description adds substantial context beyond them: the workspace counts toward the account limit, appears in the Aevia app, duplicate names are refused rather than reused, adoption renames and preserves the sandbox contents with refs still valid, and a later connection starts fresh in a new sandbox.

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 outcome, but the prose is long-winded and redundant, restating the workspace-name-passing idea twice ('return the name later calls pass as `workspace`' and 'later calls work in it by passing that name'). Several clauses could be tightened 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?

With no output schema, the description correctly states the return value (the workspace name). It covers side effects, limits, and adoption semantics thoroughly, though the interaction between the connection's default workspace and per-call `workspace` passing remains slightly tangled.

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

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

Schema coverage is 100%, so the schema already defines each parameter; a baseline of 3 would be defensible. The description nonetheless adds meaning: why `adopt_sandbox` matters behaviorally, that `workspace` name is the handle future calls use, and the ISO 14040 §4.2 framing for `goal_statement`.

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 workspace) and goes further by naming the return value that later calls pass as `workspace`. It implicitly separates itself from sibling lca_switch_workspace by noting an existing workspace is used by passing its name instead.

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 conditions for the two modes: default creates a new empty workspace and makes it the connection default, while `adopt_sandbox: true` converts an existing sandbox. It also states the refusal case (duplicate name) and how to use an existing workspace. It stops short of naming sibling tools like lca_switch_workspace explicitly.

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

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

Goes far beyond the annotations (destructiveHint=true, idempotentHint=false) by spelling out irreversibility and the precise cascade per object type: a system absorbs its assessments, assessments detach from comparisons, reports survive with dead citations. It also discloses the Execute access-level requirement and the Aevia-authored/writable-engine preconditions for `delete_engine_copy`.

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 verb and ref grammar, and the consequence sentences are information-dense rather than padded. It runs long and repeats a few schema descriptions almost verbatim, so it is efficient but not maximally tight.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers everything needed: what is removed, what is preserved, what the no-confirm call returns, and the privilege level required. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the 3-baseline applies, and the description genuinely adds meaning by tying each `ref` prefix to a specific deletion cascade and by explaining that `delete_engine_copy` is honoured only under two conditions. Some content (confirm preview wording, ref prefix list) duplicates the schema verbatim, capping this below 5.

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

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

Opens with a specific verb+resource ("Delete a saved system, assessment, comparison, analysis or report") and enumerates the exact object namespace via the `s<N>`/`a<N>`/`c<N>`/`b<N>`/`v<N>`/`r<N>` prefix scheme. An agent can distinguish this from lca_get or engine_delete without opening any schema.

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

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

Gives clear operating context: without `confirm: true` the call is a no-op preview, and a process or flow authored into an engine must go through `engine_delete` instead. It names the alternative tool and the condition that routes to it, but offers no explicit exclusion guidance for the objects it does own (e.g., how to inspect before deleting).

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: discloses the drift-tracked mirror auto-fork warning, that only unit compatibility is checked on swaps (geography/technology/year can change), that each member is linked cradle-to-gate independently, the negative-amount sign-flip semantics, and the 409 rejection tied to base_version_seq. This is rich operational context.

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

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

Dense but front-loaded: the verb, op list, mode semantics, and ref-routing all arrive before the finer behavioral notes. It is long for a description, yet nearly every clause carries distinct operational information with little 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?

No output schema exists, and the description closes that loop by naming the returned ref and the tool that consumes it (lca_run_assessment). Combined with mode, versioning, mirror-drift, and unit-handling details, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: members are `p<N>` refs and UUIDs are rejected, and the stage DAG must remain acyclic with a single sink. These constraints clarify how ops may be combined, pushing above baseline.

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

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

States a specific verb and resource ('Patch a saved composed (bill-of-materials) system') and enumerates every supported op with parenthetical glosses. It explicitly names the sibling it is not ('Linked and single-process systems are edited with lca_edit_linked'), so an agent can route correctly 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 explicit when-to-use and when-not-to-use guidance: names lca_edit_linked as the alternative for linked/single-process systems, distinguishes `mode=edit` (in place, with auto-fork of drift-tracked mirrors) from `mode=fork` (new `s<M>`), and points to lca_run_assessment for the returned ref.

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

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

Annotations only declare mutation/destructive/non-idempotent; the description adds substantial context beyond that: in-place edits append a content version, mirrors auto-fork with a warning, orphans are pruned on removal, a provider swap checks only unit compatibility so geography/technology/vintage can change, and a bare `unit_process` swap warns its background is unwired.

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

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

Front-loaded with the core action, then dense semicolon-separated clauses. Nearly every sentence carries distinct information (ops semantics, mode behavior, ref format), though the wall-of-text style is slightly heavy even for a tool this complex.

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

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

For a tool with a nested `ops` array, six op types, and no output schema, the description is remarkably complete: it enumerates each op, the mode semantics, ref format constraints, the authored-view workflow, and the single-process caveat. 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 100%, so the baseline is 3, but the description adds real meaning: refs take `p<N>`/`f<N>` and 'UUIDs are not accepted', `amount` on a link is validation-only, and `consumer_input_index` is required when a consumer has 2+ exchanges of a flow. These clarify usage beyond the schema text.

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

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

States a specific verb ('Patch') and resource (a saved linked or single-process `s<N>` system), and explicitly distinguishes itself from `lca_edit_assembly` for composed systems and notes the single-process restriction. An agent can tell it apart from siblings 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 explicit when-to-use routing: 'A single-process system takes only the two setters' and 'Composed systems use `lca_edit_assembly`'. It also points to `lca_get(ref='s<N>', form='authored')` as the way to discover edges and the required `consumer_input_index`, and explains when `fork` vs `edit` applies.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is narrower; it still adds real behavioral context: refs are numbered per-workspace and UUIDs are rejected, 'workspaces'/'engines' list globally rather than per-workspace, and the default workspace is shared across the connection and often an empty sandbox. It does not describe pagination mechanics or error behavior when both ref and kind are omitted.

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 dual-mode purpose is front-loaded in the opening clause, and the following sentences are densely informative rather than redundant. It is long and run-on in places (the ref-prefix mapping is packed inline), but nearly every clause carries load-bearing constraint or identifier information.

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

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

For a 10-parameter, dual-mode read tool with no output schema, the description covers the ref/kind split, ref syntax, workspace resolution, filter options, and the authored-vs-snapshot distinction. What remains thin is the return shape of snapshot reads and pagination behavior, though the annotations and schema carry much of the rest.

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

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

With 80% schema description coverage the baseline is 3, but the description goes further by mapping ref prefixes to their meanings (s/a/c/b/v/r<N> → system/assessment/comparison/contribution analysis/sensitivity analysis/report) and enumerating the list filters (query, system_ref, method, assessment_status), which the schema only partially documents. It also clarifies that ref/kind are mutually exclusive, adding constraint semantics absent from the flat schema.

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

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

The first sentence states a specific verb and resource with both operating modes: 'Read a saved workspace object by ref, or list systems, results or workspaces.' It is immediately distinguishable from siblings like lca_delete, lca_compose_assembly, or lca_get_task_status because it names exactly what is read and what is listed.

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

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

It gives a clear selection rule between the two modes ('Takes exactly one of `ref` ... or `kind`'), states that `ref` requires `workspace` while `kind` falls back to the connection default, and notes the auth/form caveat via 'Read this before editing a system you did not just author' in the schema. It stops short of explicitly naming alternative sibling tools (e.g. lca_edit_assembly) as the route for modification.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds rich behavior beyond that: a 45-second bounded wait, re-calling extends the wait, the three status outcomes with their payloads, the `can_retry` flag on error, and the session-scoped, one-day task_id lifetime.

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 dense sentences, front-loaded with the action and the wait semantics, then the return contract, then the eligibility and lifetime caveats. No filler.

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

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

No output schema exists, and the description compensates well by enumerating status values and their payloads. A minor gap remains around whether/how `result` refs should be passed back to `lca_get`, but overall an agent has what it needs.

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

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

Schema coverage is 100% and the schema already documents the id format, so baseline would be 3; the description adds genuine semantic value by explaining where the id originates (a previous tool call that returned a task_id) and its session/TTL constraints.

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: polls a long-running call identified by a `task_id` that was returned instead of a result. Clearly separable from siblings like `lca_get`, which it explicitly routes to for reading the saved object.

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

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

Gives both the when ('only calls that returned a `task_id` have one') and the when-not ('a tool that returned its result directly has nothing to poll'), plus names `lca_get` as the alternative for retrieving the finished object.

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

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

Adds substantial behavior beyond the annotations: preview-only without confirm, the ~45s synchronous window versus task_id escalation to lca_get_task_status, the s<N>/a<N>/c<N> materialization and refresh semantics, per-variant functional-equivalence caveat, and who is skipped or refused. The non-idempotent, non-destructive hints are neither repeated nor contradicted.

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

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

Front-loaded with purpose, then constraints, then refusal conditions — a sensible order for a complex tool. It is dense and parenthetical-heavy, but nearly every clause carries a fact an agent needs; only minor tightening is possible.

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 mutating multi-step import with no output schema, the description covers everything material: return value (primary_ref), async escape hatch, confirmation semantics, failure modes, and skip behavior. An agent can call it correctly without further probing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description still contributes: project may be a unique substring, the engine default must be writable, and the workspace/element naming conventions (s<N>, a<N>, c<N>) clarify what the parameters actually produce. It does not restate syntax the schema omits nothing of.

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

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

Opens with a precise verb+resource ('Import an openLCA project') and immediately states the composite outcome: assess each enabled variant and save one comparison. The scope (project variants, not a single product system) cleanly distinguishes it from the sibling lca_import_system.

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 strong operational context: it names engine_search(kind='project') and lca_get(kind='workspaces') for resolving parameters, states the confirm gate, and lists explicit refusal conditions (<2 or >8 enabled variants, parameter redefinitions). It never explicitly contrasts itself with lca_import_system or lca_run_assessment, so the alternative-selection guidance 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?

Adds real behavior beyond the annotations: server-side capture of the full definition (no graph read needed), drift tracking against the engine original, and the `mode=link_only` consequence (calculates live but cannot be reopened for editing). Idempotency is restated from the annotation and no permission/auth context is given, 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?

Purpose and constraints are front-loaded, but the tail paragraph on restructuring steps is post-import workflow that belongs with `lca_edit_linked`/`lca_compose_linked`. It also repeats the assessable/comparable claim twice ('immediately assessable and comparable' and 'The mirror stays fully assessable/comparable').

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

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

For a 4-param import with no output schema, the description covers the returned stable `s<N>`, idempotent behavior, mode tradeoffs, and the confirm preview flow. 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 100%, so the parameters are already documented, but the description adds meaning the schema lacks — why only `e<N>` is valid for `ref`, and the editability tradeoff behind `mode` (full vs link_only). The `confirm` preview flow is explained but largely mirrors the schema text.

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

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

States a precise verb+resource: import an engine product system `e<N>` into a workspace as a saved `s<N>`. It distinguishes itself from siblings by spelling out the accepted ref type and by routing to `lca_run_assessment`, `lca_edit_linked`, and `lca_compose_linked` for downstream work.

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 states when this is the right tool and what it rejects: only `e<N>` is accepted, a workspace `s<N>` is already imported, and a `p<N>` is not a system. It also names the concrete alternatives for restructure via `lca_edit_linked`/`lca_compose_linked`, so selection is unambiguous.

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

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

Goes well beyond the annotations: discloses the sync/async split (runs under 45s return the result directly, longer runs return a `task_id` for `lca_get_task_status`) and the persistence semantics (the assessment is always saved into `workspace` with no separate save step). These are the behaviors an agent most needs and none are in the structured fields.

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

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

Front-loaded with the core action and outcome, then the ref taxonomy, then async behavior, then sibling routing — a sensible priority order with no filler. The sentences are long and clause-heavy (semicolon-chained), which costs a little readability.

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

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

For a complex 6-parameter mutation-style tool with no output schema, the description covers the return shape (impact result or `task_id`), persistence, target kinds, and where to go for interpretation via the `assessment_interpretation` skill. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the ref 'is calculated on the database it belongs to', `nw_set` is applied after the calculation for a single score, and the assessment lands in the named workspace. The `amount` and `allocation` parameters are left to the schema, but the added ref/nw_set semantics justify a bump.

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

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

Opens with a specific verb+resource+outcome: 'Run LCIA on a target and save the result as a durable assessment (`a<N>`)'. It clearly separates this from siblings like `lca_import_system` (one-off vs tracked system) and `lca_analyze_contributions` (breakdown, not run).

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 states which ref kinds are valid (`s<N>`, `p<N>`, `e<N>` from `engine_search`) and when to use alternatives: 'a catalog `e<N>` is assessed as a one-off result and not imported as a tracked system (`lca_import_system` does that)' and '`lca_analyze_contributions` breaks a result down'. It even routes agents to `load_skill` for interpretation.

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

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

Annotations declare mutation (readOnlyHint=false), idempotency, and non-destructiveness; the description substantiates these with concrete behavior: nothing saved moves, no s/a/c/b/v refs are affected, and catalog refs stay bound to their minting database, with lca_compose_*/lca_edit_* refusing cross-database member refs. This is exactly the kind of beyond-annotation detail that earns 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?

Purpose is front-loaded in the first sentence, and the subsequent sentences on ref behavior all earn their place. It is dense and fairly long, but no sentence is filler, so it stays near the top of the range.

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 mutation tool with no output schema, the description covers the non-obvious consequences (shared default, unaffected saved systems, ref binding, compose/edit refusals) thoroughly enough that an agent needs nothing more to call it correctly.

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

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

Schema description coverage is 100% and the schema already documents case-insensitive matching, optional backticks, and verbatim copying. The description's 'as shown, matched case-insensitively' note largely restates the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Set this connection's default engine database.' It further defines the scope of that default and implicitly distinguishes itself from the sibling lca_switch_workspace by operating on the engine rather than the workspace.

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

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

Explains the context in which the default matters (browsing/composing calls that name no engine) and the downstream conditions that follow a switch, e.g. members for a new system must come from searches run afterward. It does not state explicit when-not-to-use or name an alternative switch tool directly, so it falls short of a 5.

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

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

Annotations only declare it is a non-destructive, idempotent, non-read-only mutation; the description adds that the default is shared across all conversations on the connection and can be moved by another conversation. It also warns that workspace refs are per-workspace ordinals whose meaning shifts after the switch, a consequence an agent could not infer from annotations.

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

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

Front-loaded with the action and the definition of 'default', and every sentence carries real information. The ref-ordinal passage is dense but earns its place by explaining changed resolution semantics; still, the paragraph is long enough to test an agent's parsing.

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

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

For a one-parameter, annotation-covered, no-output-schema state mutation, the description covers the operation's scope, sharing behavior, and downstream reference-resolution effects. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the name is what lca_get(kind='workspaces') shows, backticks are optional, and the value's effect is the connection-wide default. The case-sensitivity nuance is already in the schema, so credit is partial.

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

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

States a specific verb and resource ('Set this connection's default workspace') and immediately defines what 'default' means, which is the crux of the tool. An agent can distinguish it from lca_create_workspace and lca_switch_engine 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?

Explains clearly when the setting matters ('the workspace a call that names no workspace reads') and when it does not ('tools that save take `workspace` on every call and are unaffected'), which is real routing guidance. It stops short of naming sibling tools as alternatives, but the conditional framing is strong.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the description correctly focuses on what annotations cannot say: the tool takes no action, a loaded playbook persists in context, and skills are token-gated with an explicit fallback ('an unavailable request returns the available list'). That last point is valuable error-behavior disclosure, though it does not describe the playbook's size or format.

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

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

Front-loaded with the core behavior and result semantics before the enumeration. The per-skill sentences are the value-add rather than filler, though the block is long enough that it could be tightened slightly.

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

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

With no output schema, the description carries the return-value burden and does so: it states the result is a playbook and that an unknown/gated id returns the available list. Combined with the routing detail and session guidance, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the schema defines no enum and the description compensates by naming the concrete valid skill_ids and their subject matter. This adds real selection value beyond the schema's single generic string 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 ('Returns a skill's playbook as the result') with an explicit scope disclaimer ('takes no action itself'). The enumeration of skill_ids makes it unmistakable from siblings like knowledge_get_full_document or engine_get.

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?

Goes well beyond 'when to use': it routes the agent to the correct skill_id by describing what each covers ('connector_guide covers how this connection works', 'assessment_interpretation covers reading and comparing results'). It also gives the operational rule 'one load per session suffices'.

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