quipu

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

Adds substantial behavior beyond the destructiveHint/openWorldHint annotations: Turtle validation precedes the shapes-table write, the migration runs in the same transaction, and a refused migration leaves the proposal pending with nothing written. The risk-gate mechanics (plan computed, risk score compared to threshold, refusal when undetermined, override recorded in the decision note) are disclosed explicitly and are consistent with the destructive annotation.

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, then layered by mode (dry run, migration, risk gate). Dense and mostly waste-free, though the final sentence is long and packs three separate conditions into one clause.

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

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

For a 9-parameter destructive mutation with no output schema, the description carries the full burden and does: it describes the dry-run report contents, the returned plan, the failure modes, and the transactional guarantees. An agent could invoke this correctly, including safely via dry_run, from the description alone.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the coupling between accept_risk and risk_reason (the reason lands in the decision note), the risk_threshold gate including the environment-variable default, and that the computed plan is returned under the key 'plan'. It does not elaborate on limit or timestamp beyond the schema.

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

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

Opens with a specific verb+resource ('Accept a pending schema proposal') that cleanly separates it from propose_schema_change, list_proposals, and reject_proposal. The scope is narrowed further by name: only pending proposals are eligible.

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

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

Gives rich conditional guidance: use dry_run=true to preview rather than accept, and accept_risk=true plus risk_reason is required when the plan is over threshold or undetermined. It stops short of naming sibling tools (e.g. quipu_reject_proposal) as the alternative path, so it is strong context rather than explicit routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: acquisition is bounded (overflow refuses) and fails closed on unknown graphs and unsupported attachments/pins. It does not say whether data is copied into a local store, what the bound is applied against, or what 'refuse' returns to the caller.

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 resource and the source scope front-loaded, and nothing redundant. The cost is over-compression: the refusal clause is packed into a noun list that reads as terse jargon rather than clear prose.

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

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

For a four-parameter, zero-schema-coverage, no-output-schema tool operating in an unfamiliar domain, the definition leaves too much unanswered — what 'acquire' actually does to state, what tx bounds, and what the caller receives on success or refusal. Annotations cover only the read-only safety question, so the description still carries most of the explanatory burden and does not meet it.

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

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

Schema description coverage is 0% across four parameters, and the description does not compensate: source_store_id, graphs, tx and max_bytes are never explained. 'Bounded' loosely gestures at max_bytes and 'registered named graphs' at graphs, but tx is left entirely undefined and no parameter format, default or constraint is stated.

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

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

The verb+resource pair ('Acquire ... named graphs') is present, and 'from an expected MAIN store lineage' hints that graphs are pulled from a source store identified by source_store_id. However, 'complete bounded registered', 'MAIN store lineage' and 'attachments/pins' are unexplained domain jargon, and the description never distinguishes this tool from the obvious sibling quipu_acquire_composed or from quipu_import/quipu_share, which an agent could plausibly 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?

The second sentence lists refusal conditions (unknown graphs, unsupported attachments/pins, overflow) rather than when to use the tool. There is no statement of preconditions, no mention of when to pick this over quipu_acquire_composed or the import/share family, and no guidance on choosing between tx and max_bytes scoping.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds cryptic transaction/generation constraints, but it also says expected_generation is required with an explicit main tx while the schema does not list either as required, making the behavioral guidance unreliable.

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

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

The description is short and front-loads the action, but the jargon makes it hard to parse. It is concise without being clear, so structure is only adequate.

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 five-parameter tool with no output schema and no parameter descriptions, the definition is far too thin. It omits what graphs, source_store_id, and max_bytes mean, what the return value is, and how this differs from quipu_acquire.

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

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

Schema description coverage is 0%, so the description must explain all five parameters. It only gestures at expected_generation and tx, and does so inconsistently with the schema's required list, while source_store_id, graphs, and max_bytes are left unexplained.

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

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

The description states a verb and resource ('Acquire ... graphs'), but 'qualified MAIN graphs' and 'fenced attachment census' are undefined jargon. It does not distinguish this tool from the sibling quipu_acquire, leaving the agent unsure what is actually being acquired.

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

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

There is no guidance on when to use this tool versus quipu_acquire or other graph-related siblings. The sentence about expected_generation and main tx is a constraint, not a usage rule or exclusion.

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

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

Annotations already cover the write/destructive/open-world profile, so the description's added value is the concurrency semantics: recomputing expected_version would always match the set being written and 'silently discard a concurrent operator's decision'. That is genuine behavioral context beyond the annotations. It stops short of saying what a version mismatch returns or whether prior sameAs statements are overwritten.

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

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

Two sentences, front-loaded with the 'WRITE.' mode tag, then the effect, then the one non-obvious constraint. No filler; every clause carries information the agent needs before invoking.

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 write with no output schema, the description covers the mode, the effect, the graph written to, and the critical version precondition. It omits the failure mode on version mismatch and the shape of the result, which leaves a small gap for a mutation tool.

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

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

Schema coverage is 100%, so the schema already documents all five parameters, including expected_version's provenance and the set_tsv source. The description reinforces why expected_version must not be locally recomputed, which is useful meaning, but it adds nothing for actor, graph_a, or graph_b beyond what the schema says.

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 effect ('Materialise decided alignments as owl:sameAs / quipu:distinctFrom') plus the target ('derived alignment graph'). The 'decided' qualifier and the set_tsv/expected_version inputs make clear this is the terminal write step of the align_propose -> align_decide -> apply pipeline, distinguishing it from the propose/decide siblings.

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

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

Clearly implies when to use it: only after a decision, carrying the decided TSV and the version from that decision. It states the precondition strongly ('REQUIRED and must be carried from the decision') but doesn't explicitly name align_decide/align_propose as the alternatives or say what to do if the version is stale.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely new context that it "touches no store" and produces an expected_version token for the follow-up apply. It does not cover failure behavior (e.g. version mismatch, unknown pair IDs), 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?

Four short sentences, front-loaded with the READ marker and the core action, then the side-effect statement and the return contract. 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?

There is no output schema, and the description compensates by naming what comes back (decided set plus expected_version) and confirming no state is written. It omits what happens on invalid decisions or stale set_tsv, a minor gap for a 3-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 100%, so set_tsv, reviewer and decisions are already documented in the schema. The description adds only the framing that decisions are accept/negate verdicts on pairs, which is close to restating the schema; 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: apply accept/negate decisions to a proposed mapping set, and names the downrange sibling align_apply. It is clear what the tool does, though it does not explicitly distinguish itself from the analogous quipu_merge_decisions path.

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?

"Apply operator ... decisions to a proposed mapping set" plus "expected_version to carry into align_apply" situates the tool clearly between align_propose (the source of set_tsv) and align_apply. It gives no explicit exclusion of alternatives or stated prerequisites, 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it refuses unknown graph IRIs rather than returning zero candidates and explicitly exposes expected_version for downstream use.

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

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

The description is compact and front-loaded: it begins with the READ safety marker, states the core action, names the output format, and then adds only essential downstream and error behavior. Every sentence carries useful information.

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

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

There is no output schema, so the description needs to convey return shape; it does so at a high level by naming an SSSOM mapping set and expected_version. It does not describe the scoring fields or full mapping-set structure, leaving a minor gap, but it is sufficient for correct invocation in this workflow.

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

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

Schema description coverage is 100%, and the schema already explains the two graph IRIs, including the unknown-IRI refusal behavior. The description adds little parameter-specific meaning beyond restating that two named graphs are involved and omitting mapping_set_id entirely, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: propose candidate cross-graph alignments between two named graphs. It also specifies the scored SSSOM mapping-set output, which clearly distinguishes it from sibling apply/decide tools.

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

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

The description gives clear context by noting that the returned expected_version is required by align_apply, which routes the agent into the alignment workflow. It does not explicitly mention when to call align_decide or other sibling alternatives, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly, non-destructive, open-world behavior, so the safety profile is covered. The description adds the discovery-mode behavior and the fact queries are curated and self-describing, but says nothing about what happens for an unknown name, error behavior, or result shape.

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

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

Two sentences, front-loaded with the primary action, with the discovery mode placed second. The parenthetical example list is useful but slightly bulky; nothing is truly wasted.

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

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

As a dispatcher over a catalog, the description explains both modes and directs the agent to the catalog for parameter details, which is the key missing piece an agent would otherwise lack. Without an output schema, the absence of any return-value description is a minor residual gap.

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

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

Schema coverage is 100%, so both the name/graph/params fields and the discovery convention are already documented in the schema. The description adds value mainly by pointing to the self-describing catalog as the source of parameter names and types, plus a few example query names.

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 ('run a curated, parameterized named query by name') and contrasts it with the alternative of hand-writing SPARQL. It does not name the likely sibling (quipu_query) explicitly, so the differentiation is implied rather than direct.

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 operational guidance: call with no name or name='list' to discover the catalog, otherwise supply a name. It does not state when to prefer this over quipu_query or quipu_queries, so there is a small gap in 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description's 'No cursor write' adds a small amount of state-context (paging does not mutate a stored cursor), but it does not explain page size behavior, ordering, or what a page contains. Since search semantics and pagination are left unstated, this is only marginally beyond the annotations.

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

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

Three short sentences, front-loaded with the core action. Nothing is padded, though the phrase 'No cursor write' is cryptic without context and the terseness comes at the cost of usability.

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

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

There are 4 parameters at 0% schema coverage and no output schema. The description gives a minimal working context (graph scoping, 'use next_tx for the next page'), which is enough to start paging, but it does not explain `since`, `limit`, or `capture`, and without an output schema the return shape is undocumented.

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

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

Schema description coverage is 0% and the tool has 4 parameters. The description clarifies only `graph` ('scopes an exact graph'). It explains what `graph` means in context, but leaves `limit`, `since`, and the non-obvious `capture` enum (new_values / old_and_new_values / new_row) completely unexplained, so it only partially compensates for the schema's 0% coverage.

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

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

The description names a verb and resource ('Read whole transaction change pages'), which conveys a paged read of transaction changes. However, 'change pages' is internal jargon and nothing distinguishes this from sibling tools like quipu_transactions or quipu_graph_events, so an agent cannot confidently pick it over those siblings.

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

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

The only routing hint is 'graph scopes an exact graph', which is a scoping note rather than a when-to-use rule. There is no statement of when to prefer this over quipu_transactions, quipu_graph_events, or quipu_events, and 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results are entities plus their facts and that link expansion is optional, but it says nothing about truncation, ranking defaults, or what happens when the query matches nothing — gaps that matter for a retrieval tool whose output shape is otherwise undocumented.

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, front-loaded clauses: the action and return shape come first, the optional expansion second. Little is wasted, though "ready to prime an agent" is slightly promotional rather than informational.

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 some of the burden and does state that entities and facts come back. For a four-parameter retrieval tool in a crowded search family, however, it lacks result limits, ordering semantics, and any statement of how scope (graph/namespace) is determined — leaving calling behavior partly undefined.

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 explains query, ppr_rerank, expand_links, and max_entities. The description's "Optionally expand to linked entities" merely restates the expand_links parameter without adding syntax, tradeoffs, or guidance on when the expansion or PageRank reranking is worth enabling, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ("Query the knowledge graph") and states the shape of the result ("relevant entities and their facts, ready to prime an agent"), which is more than a restatement of the name. It does not, however, distinguish itself from the many retrieval siblings such as quipu_search, quipu_unified_search, quipu_hybrid_search, or quipu_ask, so an agent must guess which retrieval entry point 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?

"Ready to prime an agent" implies the intended use case (context priming before an agent task), and "Optionally expand to linked entities" hints at a broader-vs-narrower retrieval choice. There is no explicit when-to-use or when-not-to-use guidance and no named alternative among the numerous search siblings, so routing must be inferred.

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 readOnlyHint/openWorldHint/non-destructive annotations by disclosing the result ordering ('ordered by overlap strength'), the determinism/auditability guarantee, and the underlying provenance semantics that determine what qualifies as a match. What it does not cover is cardinality or result limits, which matters for an open-world query.

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

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

The core definition and its differentiating clause are front-loaded, and the dense phrasing earns its space by packing join semantics, ordering, and bitemporal behavior into three sentences. The terminology ('Bead', 'touched code entity') assumes domain familiarity, which slightly raises the reading burden.

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-shape burden and does so adequately by specifying that it returns other work-items sharing at least one entity, ordered by overlap strength. It is thin on result cardinality, truncation behavior, and what an empty result means, which a graph-traversal query arguably should disclose.

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%, establishing a baseline of 3, and the description adds real meaning on top by framing valid_at as the 'as of <date>' point-in-time question, which is more actionable than the schema's generic ISO-8601 'valid-time filtering'. The tx parameter is left entirely to the schema, so the addition is partial rather than comprehensive.

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 (returns the other work-items) against a specific input (work-item/Bead IRI) and explains the exact join path via the provenance chain Bead <-implements- GitCommit -modifies-> entity. The phrase 'graph query over typed provenance edges, not a statistical mine' distinguishes it from sibling analytics tools such as quipu_impact or quipu_path_cone.

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

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

Provides clear context for when the tool applies (co-occurrence of touched code entities) and explicitly scopes the bitemporal mode with 'pass valid_at for which work co-occurred as of <date>'. It does not name a concrete alternative or state when NOT to use it, so the agent must infer routing from the sibling list rather than being told.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond that: it does not disclose ordering of results, whether the list is complete or truncated, how the default limit of 100 interacts with large graphs, or what errors look like. With annotations carrying the behavioral load, this is adequate but minimal.

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

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

A single front-loaded sentence with the verb and resource first and the filter modifier second. No filler, no restating of the name or 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?

There is no output schema, so the description carries the burden of explaining what a returned entity looks like (IRI plus label? all triples? counts?) and it does not. For a graph listing tool in a very large sibling set, it also fails to signal result-shape or paging expectations, leaving an agent to discover them by trial.

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

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

Schema description coverage is 100%, so all three parameters (type as rdf:type IRI, predicate as predicate IRI, limit with default 100) are already documented in the schema. The description echoes the type/predicate filters but omits the limit parameter entirely and adds no IRI format examples or precedence rules when both filters are supplied. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('List entities in the knowledge graph') plus the optional filter modes, so an agent knows exactly what the tool returns conceptually. It stops short of distinguishing this from closely related siblings such as quipu_entity, quipu_search_nodes, or quipu_spotlight, and the opaque name 'quipu_cord' provides no supporting signal.

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

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

There is no guidance on when to choose this listing tool over the numerous sibling query/search tools (quipu_query, quipu_search_nodes, quipu_unified_search, quipu_entity). The phrase 'optionally filtered' hints at flexibility but names no conditions, prerequisites, or alternatives.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the risk profile is known without the description. The description adds real semantics beyond that (non-implicit activation, free overlap, consumption via FROM), but never warns that the `remove` action deletes the named grouping or that `create` records an actor. Adequate, not rich.

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 definition and followed by the one operational fact that matters (FROM resolves over members), plus a scoping caveat. No filler whatsoever.

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

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

There is no output schema and four distinct actions (create/list/show/remove) behind a single tool, yet the description never mentions any of them or what show/list return. The concept is explained well, but for a multi-action, destructive, open-world tool this leaves the agent to infer action-level behaviour from the schema alone.

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

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

Schema description coverage is 100%, so parameters are fully documented structurally and the baseline is 3. The description's only added meaning is the FROM/membership semantics, which is conceptual rather than parameter-level; it does not explain the actor, timestamp, or ordering behaviour of `members`.

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 ('Manage named datasets') and defines the concept precisely as a reusable name over an arbitrary set of graphs, including how it is consumed via `FROM <dataset-iri>`. That is enough for an agent to distinguish it from graph-level siblings like quipu_graph_create, though no sibling is named explicitly.

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

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

Provides one important usage constraint ('never implicitly active') and notes that datasets may overlap, which shapes how an agent should reason about them. It gives no explicit when-to-use or when-not-to-use guidance relative to quipu_graph_create, quipu_graph_label, or quipu_graph_list.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is largely covered. The description usefully adds that the call consumes external embedding resources (cost/latency) and persists vectors (side effect with no undo), but says nothing about idempotency, resumability, or scope of what is overwritten.

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

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

Two short sentences, front-loaded with the action and target, followed by the operational caveats. Every clause adds information: provider source, external resource consumption, and vector persistence.

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 parameters, no output schema, and annotations carrying the safety profile, the description supplies enough to call it correctly: what it fills, with what, and that it costs external resources and writes vectors. Only the choice against quipu_embed_backfill_graph and any run-length/idempotency expectations are left open.

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 there are no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misrepresents or omits parameter behavior.

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 (backfill) and resource (missing ROOT entity embeddings) plus the mechanism (configured provider). The 'ROOT entity' scoping implicitly separates it from the sibling quipu_embed_backfill_graph, but the sibling is never named, leaving the agent to infer the distinction.

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

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

Usage is only implied by 'missing' embeddings – run it when embeddings are absent. There is no explicit when-to-use, when-not-to-use, or routing guidance relative to quipu_embed_backfill_graph, which is the obvious alternative for a backfill task.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds real value by narrowing the blast radius ('does not rewrite ROOT entity text'), but never says what does get overwritten, whether existing embeddings are replaced or skipped, or what cost/rate limits apply.

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

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

A single front-loaded sentence with zero filler, and the exclusion clause is placed where it is most useful. It is slightly cryptic — 'ROOT entity text' is never defined — but nothing is wasted.

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

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

For a destructive, open-world mutation with no output schema and no documented parameters, the description is too thin. It omits idempotency/resumability, what a backfill call returns, and any indication of side effects beyond the ROOT exclusion, which an agent needs before triggering it.

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

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

Schema description coverage is 0%, so the description must carry the load. It does map loosely onto both params ('named-graph' → graph, 'bounded number' → max_entities), but gives no format for the graph identifier and no default or upper bound for max_entities, so an agent still guesses at valid values.

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

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

States a specific verb (backfill), a specific resource (named-graph entity embeddings), and a scope constraint (a bounded number). The 'named-graph' qualifier implicitly separates it from the sibling quipu_embed_backfill, though that 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?

There is no guidance on when to choose this over quipu_embed_backfill, no prerequisites (graph must exist / be unfrozen), and no advice on how to size max_entities. 'Bounded number' hints at incremental batching but leaves the operator to infer it.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral note, that IRIs are passed as encoded query values including slashes and fragments, but says nothing about what happens when the IRI is unknown, whether an error or empty result is returned, or how dereferencing behaves across the open world.

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, front-loaded with the core action and followed by the one non-obvious encoding caveat. There is no filler or restatement of the tool name.

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

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

For a two-parameter, read-only dereference tool with no output schema, the description covers the action and the encoding quirk but omits failure behavior and any hint at the JSON-LD shape returned, which is the main thing an agent cannot get from the empty schema or the annotations.

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 carry both parameters, and it makes a partial attempt: it explains that slashes and fragments in 'iri' are encoded as query values, and that 'expanded' relates to label expansion. However, 'label expansion' is left vague, and the encoding note implies format handling without stating how the caller should encode 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?

The description states a specific verb-and-resource pair: 'Dereference an exact IRI as JSON-LD'. The word 'exact' signals scope, which helps separate it from siblings like quipu_search or quipu_entity_ref, although no sibling is named explicitly.

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

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

Usage is only implied: the agent must infer it should call this when it already holds a fully qualified IRI. No explicit when-to-use or when-not-to-use guidance is given, and the closely related quipu_entity_ref and quipu_search tools are never mentioned or contrasted.

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

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

Annotations already establish readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety behavior is covered. The description adds meaningful semantic context beyond annotations by warning that current MAIN-history semantics do not certify composed/named-graph audit completeness, which affects how an agent should interpret results.

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

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

The description is two sentences and front-loads the core action before adding the important limitation. It is efficient, though the second sentence uses dense domain terminology that could confuse an agent unfamiliar with MAIN-history semantics.

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

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

For a one-parameter read-only tool with no output schema, the description covers purpose and an important audit caveat. It remains incomplete because it does not explain what the history result contains, such as whether it returns events, revisions, or ordering information.

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

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

Schema description coverage is 0%, and the single iri parameter is only typed as a string in the schema. The description adds that the IRI must be exact, which is useful, but it does not document IRI syntax or provide examples, so compensation for the low schema coverage is only partial.

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

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

The description states a specific verb and resource: read the entity-history endpoint for an exact IRI. It is clear what the tool does, though it does not explicitly distinguish itself from nearby siblings such as quipu_entity, quipu_events, or quipu_graph_events.

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 “for an exact IRI,” and the caveat about MAIN-history semantics usefully warns against relying on it for composed/named-graph audit completeness. However, it does not explicitly name the alternative tool or state the positive conditions under which this tool should be preferred.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the mutation risk is known from structured data. The description adds genuinely useful behavior beyond that: verify does not fetch, and an uncertain mint response must be reconciled rather than retried. It does not say what a mint overwrites, what permissions are needed, or what happens to the entity when the same keys converge.

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 operational vocabulary front-loaded and the safety warning placed last where it is most likely to be read as a constraint. Nothing is padding, though the phrasing is dense enough that the mapping between the three verbs and their parameters is hard to extract.

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

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

This is a destructive, open-world mutation tool with nine parameters, 11% schema coverage and no output schema, so the description needs to do heavy lifting. It supplies only a retry warning and a no-fetch note, leaving action-specific parameter requirements and the shape of a mint or resolve result entirely undocumented.

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 only 11%, so the description must carry the parameter burden and largely fails to. It gestures at the semantics of mint/resolve/verify and the key-triple relationship, but eight of nine parameters (iri, asOf, type, graph, label, source, namespace) get no explanation whatsoever.

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 three specific operations (mint a typed stable entity, resolve a registered reference, verify a local key IRI) that map cleanly onto the action enum, so an agent can tell what each mode does. It stops short of distinguishing this tool from siblings such as quipu_entity or quipu_resolve_entity, which sound like they cover overlapping territory.

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

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

There is no explicit when-to-use guidance or routing advice against the many sibling entity tools. The phrase 'without fetching' hints at a cheap local verification path, and the reconciliation warning implies a retry policy, but neither tells the agent which situation selects this tool over quipu_entity or quipu_resolve_entity.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the description should explain what is destroyed or overwritten — notably that replace_snapshot 'replaces facts previously asserted by this episode' and that shapes trigger SHACL validation. It says none of this, leaving the destructive profile unexplained beyond the annotation 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?

A single front-loaded sentence with no filler. The brevity itself is the problem, but as structure and economy go it is clean and easy to parse.

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?

A nine-parameter mutation tool with a destructive annotation, an optional replace_snapshot flag, and SHACL shape input needs more than one line. Nothing explains mutation scope, idempotency, validation failure behavior, or the relationship between the natural-language episode_body and the node/edge payload.

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 all nine parameters are already documented in the schema, which sets the baseline at 3. The phrase '(nodes + edges)' marginally signals two of the parameters but adds no semantics about how episode_body, graph, or shapes interact.

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 verb 'Ingest' plus 'structured knowledge from an agent episode (nodes + edges)' identifies the general operation, but 'ingest structured knowledge' is vague about what actually lands in the system. With ~80 siblings including quipu_knot, quipu_retract_episode, and quipu_episodes_complete, the description does nothing to distinguish this tool from adjacent write paths.

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

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

There is no when-to-use guidance, no prerequisites (group_id, destination graph, SHACL shapes), and no mention of alternatives such as quipu_knot or quipu_import. An agent must infer usage entirely from the 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 a write with destructiveHint=true and openWorldHint=true, so the description owes the agent context it cannot get there. It adds nothing about what ingestion replaces or merges, whether existing episodes with the same name are overwritten, or what graph-visible side effects occur — precisely the concerns a destructiveHint raises.

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, front-loaded with what the tool is and followed by what it accepts. No filler, though 'Graphiti-compatible' is jargon that will not help every agent.

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

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

For a five-parameter ingestion tool marked destructive with no output schema, the description leaves too much open: no return information, no note on deduplication or overwrite behavior, and no mention of the timestamp parameter. It is not sufficient for an agent to call it safely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description enumerates name, body, group, and source, which matches the schema without adding format, defaults, or semantics; it also omits timestamp entirely.

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 (ingest) and resource (episode), and adds that it is a 'Graphiti-compatible flat' form that converts to a Quipu episode. That is more than a restatement of the name. It does not, however, distinguish it from nearby siblings such as quipu_episode or quipu_import, so an agent cannot tell which ingestion path applies.

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

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

There is no guidance on when to use this versus quipu_episode, quipu_import, or quipu_acquire, nor any note about prerequisites or valid group values. The 'Graphiti-compatible' phrase implies a use case but never states it as a condition.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: reading does not advance a consumer cursor (a state side-effect an agent must know), and it discloses parameter precedence ("since overrides consumer"). It stops short of return shape, pagination, or default limit 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?

Four short clauses, front-loaded with the core action and the cursor caveat, then parameter disambiguation, then the sibling pointer. No filler, no repetition of schema structure, and every sentence adds distinct 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 5-parameter read tool with no output schema, the description covers the disambiguation that matters (root vs graph, since vs consumer, group semantics) and annotations cover safety. Gaps remain around limit's meaning/defaults and what an event record looks like, but nothing blocks a 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%, so the description must carry parameter meaning, and it does for most: since/consumer precedence, types as a comma-separated event-type filter, and the important clarification that group is an episode group rather than a graph selector. Only limit is left entirely undefined, which keeps it off 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 ("Read a bounded batch of ROOT's events") plus the critical scope qualifier "without committing a consumer cursor." It explicitly names the sibling that handles the graph case (quipu_graph_events), so an agent can distinguish the two without opening either schema.

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

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

Gives a clear routing rule: root-scope events here, named-graph events via quipu_graph_events. The non-committing behavior also implicitly separates it from quipu_events_commit, though that sibling is never named and no explicit exclusion against the commit variant is stated.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description earns credit by explaining the reason — a lower offset rewinds the cursor and forces redelivery, and reading events does not advance state. It omits auth requirements, idempotency of repeated commits, and whether stale/unknown consumer_ids error.

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, no filler: the action first, then the two non-obvious semantics (rewind, delivery != commit). Every clause carries information an agent needs.

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

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

No output schema exists, so the description should say what a successful commit returns (new cursor value, version, error on stale offset) and should define consumer_id. Given only two parameters it is close to adequate, but the missing return/error semantics leave a real gap for a destructive, open-world mutation.

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

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

Schema description coverage is 0%, so the description carries the full burden. It does give directional meaning to 'offset' (lower values rewind), but says nothing about what consumer_id identifies, its expected format, or what units/ordering the offset uses relative to offsets returned by quipu_events.

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 ('Durably set a consumer cursor'), which separates it from the read-only sibling quipu_events and from quipu_graph_events_commit by naming 'consumer' scope. It stops short of explicitly distinguishing itself from those siblings, so an agent still has to infer the 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?

'delivery alone never commits' implies this tool is the required follow-up step after receiving events, which is implicit usage guidance. No alternative is named and no precondition (e.g. must the consumer exist / be registered) is stated, so the guidance is inferred 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the 'Read-only' tag adds little. The real value is behavioral detail beyond annotations: output shape differs by fact kind, owl:materialize results recurse premises to base facts, and re-matching is described as happening 'currently' (i.e., the answer is evaluated at call time, not stored). It does not say what happens for an unknown or non-existent fact, which is the main missing behavioral note.

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 front-loaded sentence gives the core action, then a semicolon-separated enumeration of the three answer shapes, ending with a short safety tag. Every clause carries information; no filler. It is dense to the point of being terse, and the trailing 'Read-only' duplicates an annotation, but the structure is otherwise 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?

There is no output schema, so the description has to characterize return values — and it does so thoroughly for the three fact kinds, which is the crux of this tool. With a complete input schema and accurate annotations, the remaining gaps (behavior on a missing fact, pagination/size of a deep recursion) are modest rather than crippling.

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 s/p/o and depth are already documented as IRIs, a literal, and a recursion depth default of 5. The description clarifies that the three parameters together denote a single fact whose derivation is walked and that recursion bottoms out at base facts, which helps interpret depth. It does not add format or edge-case semantics (e.g., literal typing, depth=0 behavior) beyond the schema, so baseline 3 fits.

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 and resource ('Walk a fact's derivation chain') and then enumerates three fact kinds and exactly what each returns (transaction/source, rule id + re-matched premises, axiom families recursed to base facts). That is far more precise than a name restatement. It stops short of naming a sibling such as quipu_reason or quipu_impact as the contrasting operation, so the differentiation is implicit 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?

Usage is implied by the 'explain a derivation' framing: an agent can infer it is the provenance-inspection tool rather than the derivation-producing one. However, there is no explicit when-to-use/when-not-to-use statement, no prerequisites, and no named alternative among the many quipu_* reasoning/graph tools. Guidance is adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds the mutual-exclusivity constraint and the ROOT fallback, but says nothing about export volume, determinism guarantees, or what happens with a CONSTRUCT returning empty results — and the schema's 'Unknown IRI is an error' is the only failure mode 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?

Two sentences, no filler. The scoping options come first and the mutual-exclusivity rule lands immediately after, which is exactly the ordering an agent needs.

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 four-parameter, no-required-args, no-output-schema export tool this covers the essentials: scope modes, default behavior, exclusivity, and error on unknown IRI. Only the meaning of 'deterministic' and any size/streaming expectations are left implicit.

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

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

Schema coverage is 100%, so per-parameter meaning is already handled, but the description contributes a cross-parameter constraint absent from the schema: the scope fields are mutually exclusive. That is genuine added semantics that prevents a malformed call combining graph and group_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 ('Export deterministic RDF') and enumerates the four scoping modes (named graph, provenance group, SPARQL CONSTRUCT, ROOT default). An agent can tell this is a read-only serialization tool, though it never names a sibling such as quipu_query or quipu_import to sharpen the 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?

Provides real invocation guidance: 'ROOT when no scope is supplied' and 'Scope fields are mutually exclusive' tell the agent how to pick parameters. It stops short of saying when to prefer this tool over alternatives like quipu_query for querying or quipu_import for the inverse direction.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavior in "bounded" (results are capped/paged) and wildcard semantics for omitted terms, but it omits what an unbounded pattern (all terms absent) does to cost, whether there are max pageSize limits, and anything about result structure.

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 no filler; the pagination/wildcard note comes second where it belongs. It is efficient, though the terseness is achieved by dropping information rather than by compressing it.

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

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

For a 5-parameter, 0%-documented, open-world query tool with no output schema, the description leaves too much undefined: what a "fragment" contains, whether omitted terms yield a full scan, pagination limits, and any indication of result shape or ordering. An agent could call it but could not predict cost or interpret what comes back.

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 carry the full burden and does partially: it explains that page/pageSize control pagination and that missing subject/object/predicate act as wildcards. It adds no meaning about match mode (exact IRI vs substring vs prefix), value formats, defaults, or page-size bounds, so half the semantic load is still missing.

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?

"Read a bounded triple-pattern fragment" gives a verb (read) and a resource (triple-pattern fragment), which is more than a tautology, but "fragment" and "bounded" are unexplained jargon and nothing distinguishes this from sibling retrieval tools like quipu_query, quipu_search_facts, or quipu_knot. An agent can guess this is pattern-based triple retrieval but not how it differs from the many other query surfaces.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of any alternative among the ~70 siblings, several of which (quipu_query, quipu_hybrid_search, quipu_search_facts, quipu_unified_search) plausibly overlap. The only implicit usage signal is "absent terms are wildcards," which describes mechanics, 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?

Beyond the readOnly/openWorld/non-destructive annotations, it discloses the default filters (prov:Activity episodes, rdf/rdfs/prov scaffolding predicates), the ranking and capping behavior of nodes, and — critically — that the response self-reports what was dropped. That truncation disclosure is exactly the kind of behavioral detail annotations cannot express.

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

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

Three sentences, front-loaded with the return payload, followed by default exclusions and then capping/truncation reporting. The first sentence is dense with parenthetical field lists but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing return values and does so concretely (node fields, edge tuple format, census ordering). Minor gaps remain: how limit and edge_budget interact when both bite, and edge ordering, are left unspecified.

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 type, limit, and include_episodes are already documented in detail, including the default 250 and hard max 2000. The description reinforces the degree-ranked capping and the episode exclusion but adds little semantic detail beyond the schema, and edge_budget is not discussed at all.

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?

"Project the knowledge graph into a render-ready node-link payload" gives a specific verb and resource, and the enumeration of the returned shape (nodes, indexed edges, type census) makes it unmistakably a visualization/graph-dump tool rather than a query tool. It stops short of naming a sibling such as quipu_query or quipu_export to clarify the 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?

The description implies usage (you want a renderable node-link payload in one call, rather than paginating a query) and explains the default scope choice so the domain graph is not buried in provenance. It never explicitly states when to prefer this over quipu_query, quipu_graph_list, or quipu_export.

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 the safety envelope (not read-only, open-world, destructive), and the description adds non-trivial semantics beyond them: the call is idempotent, an existing graph keeps its original creation timestamp and declared actor, and interning terms is not a substitute. The one unexplained tension is destructiveHint=true against an explicitly idempotent, non-overwriting operation, which the description never reconciles.

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 action and the prerequisite, then the idempotency rule, then the clarifying exclusion. No sentence is redundant with another or with the schema.

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

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

For a three-parameter registration call with full schema coverage and annotations covering safety, the description supplies the two facts it must: when registration is required and how repeat calls behave. Return values are not described, but no output schema exists and the idempotency note implies the record is stable, which is sufficient 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 coverage is 100% and each parameter is already documented, including that actor is a declared creator rather than authenticated identity. The description adds no parameter-level detail such as IRI form, default-resolution behavior for timestamp, or what happens when registering an existing graph with a different actor; 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 ("Register a committed named graph") and scopes it to the graph-registration step that must precede graph-scoped knot writes or labeling, which separates it from the write/label siblings by implication. It stops short of naming those siblings explicitly, so an agent must infer the boundary from the phrasings "knot writes" and "labeling."

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 ordering guidance ("before graph-scoped knot writes or labeling") and one explicit exclusion ("Interned terms are not registration"), which is exactly the kind of when-not signal that prevents misuse. It does not name an alternative tool to call instead, so no fallback routing is offered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered, and the description usefully adds that no cursor is persisted. However, it says nothing about ordering, what happens when 'since' is omitted, whether the batch is resumable, or what the returned log/offset entries look like. For a read tool with annotations, this is adequate but not rich.

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 scope constraint before the routing hint. No filler or redundant restatement of the tool name.

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

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

With six entirely undocumented parameters, no output schema, and no explanation of event shape or offset semantics, the definition is too thin for a tool whose main value is paging a per-graph log. The read-only nature is clear, but an agent would have to guess at 'group', 'consumer', and 'since' semantics.

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 carry the burden for six parameters, yet it only hints at 'limit' via 'bounded batch' and waves the rest away with 'Same filters as quipu_events'. Nothing explains what 'graph', 'group', 'since', 'types', or 'consumer' mean here or how they interact, leaving the agent to infer semantics from a sibling it cannot see.

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

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

States a concrete verb+resource pair ('Read a bounded batch of ONE registered committed named graph's events') and pins the scope to a single named graph, explicitly contrasting with the global quipu_events sibling. The phrase 'without committing a cursor' implicitly distinguishes it from quipu_graph_events_commit, so an agent can pick correctly without opening either schema.

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

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

'without committing a cursor' gives the key selection condition versus the commit variant, and 'Same filters as quipu_events' points to the reference tool for filter behavior. There is no explicit statement of when not to use it or of prerequisites, 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?

The annotations declare destructiveHint=true and openWorldHint=true; the description adds real value by explaining that durability is guaranteed and that passing a lower offset explicitly rewinds the cursor. That rewind note is precisely the behavioral consequence behind the destructive flag, which structured data alone would not reveal. It does not mention auth/registration requirements or error behavior for unknown consumers or unregistered graphs.

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 tightly packed sentences with zero padding, and the primary action is front-loaded ahead of the rewind caveat. Every clause carries information an agent needs.

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

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

Annotations cover the safety profile and there is no output schema to explain, so the bar is moderate and mostly met. However, for a destructive mutation whose parameters are wholly undocumented in the schema, the description should say what happens when the consumer or graph does not exist and whether the operation is idempotent.

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 carry parameter meaning, and it only partially does. It clarifies that 'offset' has rewind semantics and that 'graph' must be a registered committed graph, but 'consumer_id' is entirely unexplained, and neither the offset's relationship to the graph's event log nor whether consumer registration is implicit is documented.

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: durably setting a consumer cursor in a named graph's event log, with a scope constraint ('one registered committed named graph'). It is clearly distinct from listing tools like quipu_graph_events or quipu_events, but it does nothing to separate itself from the near-namesake sibling quipu_events_commit, so an agent must still infer the difference from the 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?

Usage is only implied: the phrasing indicates this is the write-side counterpart to reading events, and 'one registered committed named graph' hints at a precondition. There is no explicit when-to-use, no when-not, and neither quipu_events_commit nor quipu_graph_events is named as an alternative.

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

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

Annotations only declare destructiveHint/readOnlyHint/openWorldHint; the description goes well beyond them by disclosing that history including retracted rows and transactions is preserved, that the copy is hash-verified before deletion, and that the graph remains addressable at the same IRI. This is exactly the context an agent needs before authorizing an irreversible-looking destructive 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?

The destructive core (export, verify, delete, re-attach) is front-loaded in one dense sentence and the reading-back and refusal clauses follow logically. It is long but nearly every clause carries operational meaning; only the frozen-dataset URN reference borders on jargon-heavy.

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

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

For a destructive multi-step tool with no output schema, the description covers reversibility, archive location behavior, post-freeze addressability, and refusal cases. Minor gaps remain: no permission/auth requirements for performing a freeze and no statement of what the tool returns on success or on hash-verification failure.

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 graph, timestamp, actor and out_dir are already documented in the schema, including out_dir's default. The description adds no extra semantics about parameter formats or interactions, so the baseline of 3 applies.

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

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

The description names a specific verb and resource (deep-freeze a named graph) and enumerates the exact mechanics: export full history, hash-verify, delete local rows, re-attach the pack. It is immediately distinguishable from the inverse sibling quipu_graph_thaw and from plain export tools like quipu_export.

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 states the conditions under which the tool refuses to run (ROOT, meta-graph, overlays, attached graphs, double-freeze) and explains how to read the result afterwards via FROM <iri>, the frozen dataset URN, or include_kinds:["archive"]. It never explicitly contrasts with quipu_graph_thaw as the inverse operation, so the when-to-use framing is strong but not fully closed.

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

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

Annotations already declare this is not read-only, is open-world, and is destructive. The description adds useful context that declarations are versioned and that policy tokens describe data rather than authorization. It still does not explain what the destructive effect is, whether existing labels are replaced, what permissions are required, or how failures behave.

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

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

The description is three tight sentences with the core action and prerequisite front-loaded, and no obvious filler. It is structurally clear, though it is arguably too sparse for a nine-parameter destructive operation.

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

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

This is a complex mutation tool with nine parameters, a nested trust object, no output schema, and destructive annotations. The description covers the graph prerequisite and an authorization caveat, but it leaves out most operational details an agent needs, including parameter meanings, effects on existing labels, and return behavior.

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 nine parameters, including a nested trust object, but the description only touches on graph and policy semantics. It does not clarify kind, actor, trust.iri/chain/rank, valid_to, freshness, durability, or timestamp formats and constraints. With such low schema coverage, the description does not compensate for the missing parameter meaning.

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

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

The description gives a specific verb and resource: "Declare lattice labels" on an "already registered committed graph." It also clearly routes users to quipu_graph_create first, distinguishing this from graph creation. However, "lattice labels" is not explained, and it does not differentiate this tool from other graph mutation siblings such as freeze, thaw, or events commit.

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 only explicit guidance is the prerequisite "Create first with quipu_graph_create," which implies this tool should be used after a committed graph exists. There is no when-not guidance, no mention of graph state constraints such as frozen graphs, and no comparison with alternative graph-labeling or graph-event tools.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real behavioral context: it discloses what each result carries (class, source, lifecycle, labels for freshness/durability/trust/policy/kind), that `graph` mode skips "materialization enrichment," and the backward-compatibility signal that a store lacking this tool predates the graph-kinds surface. It does not explain what materialization enrichment actually means, which is the one unclear behavioral term.

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 listing purpose and the `graph` special case come first, then what is returned, then filter syntax, then the capability-probe note. No sentence is filler, though the jargon ("materialization enrichment," "dataKind token") adds cognitive load that a short gloss would fix.

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 usefully enumerates the fields returned and the four label dimensions, and it covers mode conflicts and the version-compat signal. It leaves a couple of loose ends for a 3-parameter tool: no pagination or result-size behavior, and the undefined "materialization enrichment" term.

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 would be 3, but the description goes beyond the schema by giving concrete token examples for `kind` (operational | archive) and the only enum value for `lifecycle` (frozen). It also restates and reinforces the mutual-exclusion constraint on `graph`, which is the schema's most consequential semantic detail.

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

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

States a specific verb and resource ("List registered named graphs") and immediately clarifies the one-exact-IRI variant versus the filtered-list variant. It is distinguishable from siblings such as quipu_graph_create, quipu_graph_label and quipu_graph_freeze because the description scopes itself to enumeration and filtering, not mutation.

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 gives the two modes of use — pass `graph` for one exact IRI, or filter with `kind` and/or `lifecycle` — and states the exclusion that `graph` cannot be combined with kind/lifecycle. It also frames itself as a capability probe for the graph-kinds surface. It stops short of naming a sibling to use instead when the agent actually wants to create, label, or freeze a graph.

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 flag this as destructive and open-world, and the description meaningfully adds to that picture by disclosing that the pack file is retained on disk and the freeze registry row is closed rather than deleted, which tells the agent the operation is recoverable/reversible in spirit. It still omits failure semantics – what state the graph is left in if pack verification or restoration fails – and gives no warning about the detach window.

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

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

Two sentences, zero filler, with the operation name and the full effect chain front-loaded in the first sentence and the persistence guarantee placed second. Every clause carries information an agent needs.

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 multi-step mutation with no output schema and fully documented parameters, the description covers the sequence of side effects and the durability of artifacts, which is the key missing piece elsewhere. It falls short only on failure/partial-completion behavior and authorization requirements, which matter given the destructive hint.

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

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

Schema description coverage is 100% with only three flat string parameters, so the schema already documents graph, actor, and timestamp. The description reinforces that restoration happens "under the same IRI", implying the graph identifier is reused verbatim rather than reassigned, but adds no format or constraint detail beyond what is already structured. Baseline 3 applies.

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

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

The description opens with a specific verb and resource ("Thaw a frozen graph") and then enumerates the exact sequence of effects: verify archive pack, detach, restore history under the same IRI, reopen for writes. This clearly marks it as the inverse of the sibling quipu_graph_freeze, so an agent can distinguish the two 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?

Usage is only implied by the phrase "frozen graph" – the agent can infer the tool applies exclusively to graphs in the frozen state. There is no explicit statement of when to prefer it over alternatives, no prerequisite checks (must the graph already be frozen? what if only partially archived?), and no guidance on the required timestamp semantics.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious semantics beyond them: a healthy result is a positive signal only and does not prove complete graph coverage, which prevents an agent from over-trusting the response.

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

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

A single sentence, front-loaded with the action and followed by the one caveat that actually changes interpretation. No filler, no restatement of the name or title.

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

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

For a no-parameter liveness probe with no output schema, the description covers the essential unknown – how much a success actually proves. It stops slightly short of indicating what the health payload conveys, but that gap is minor at this complexity.

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 schema baseline is 4. There is nothing parameter-wise the description could usefully add, and it does not waste space restating the empty input.

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 ("Read server health") and adds the scope qualifier that it is a liveness control rather than a completeness check. It is distinguishable from data-returning siblings such as quipu_stats or quipu_version by the words "positive liveness control," though it does not name those siblings 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?

"As a positive liveness control" implies the when-to-use case, and the caveat hints at when not to rely on it, but no concrete alternative (e.g. quipu_stats for coverage, quipu_version for build info) is named. An agent must infer which sibling to reach for when it needs more than a liveness 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral value by disclosing that only simple type constraints are pushed into the ANN index (so complex filter shapes degrade) and that the filtered path is O(log n). It omits cost/preconditions for the embedding path and the result ordering.

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

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

Three tight sentences, front-loaded with what the tool is, then accepted inputs, then the pushdown constraint. No filler, though the O(log n) claim is more marketing than decision-relevant for an agent.

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

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

There is no output schema, so the description should clarify what comes back; it only indirectly implies entity IRIs via the SPARQL schema text, and never states whether scores are returned or how results are ranked. For a tool with two alternative input modes and a conditional embedding path, that is a meaningful remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns slightly more by tying the sparql parameter's pushdown benefit to a concrete pattern shape (e.g. ?s a <Type>) and by framing embedding and query as interchangeable inputs, reinforcing the precedence rule the schema already states.

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 composite resource: combined SPARQL + vector similarity search, plus the distinguishing mechanism (predicate pushdown). An agent can distinguish it from a pure SPARQL or pure vector tool, though it never names a specific sibling such as quipu_search or quipu_query to sharpen the contrast.

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 mention of 'combined' search and pushdown hints that this tool is for filtered semantic retrieval, and 'simple type constraints' implies a boundary. But there is no explicit when-to-use, when-not, or named alternative among the many search siblings, and no mention that an EmbeddingProvider must be attached for the query 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?

The description adds real behavioral context about counterfactual mode, but its closing claim 'The store is never mutated' sits in direct tension with annotations declaring readOnlyHint=false and destructiveHint=true, so an agent gets conflicting safety signals about a graph-mutating-looking operation. It also does not explain what the tool actually returns (reached set, edges, depth info) despite there being no output schema.

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

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

Three short sentences, front-loaded with the core action and then the modifier mode, with no filler. The only weakness is that the final sentence is the one that introduces the annotation conflict rather than clarifying behavior.

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

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

For a 6-parameter traversal tool with no output schema, the definition never describes the shape of the result (what a 'reached set' contains, how hops/predicates affect it, what ppr scores look like), leaving the agent guessing about output. It does cover the single most surprising mode (remove=true), but the completeness is only adequate.

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

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

Schema description coverage is 100%, so the schema already documents hops, predicates, timestamp, and rank_by_ppr. The description only elaborates on remove=true, and even that largely restates the schema's 'speculatively retract the entity before walking (counterfactual mode)'. Baseline 3 applies since the description adds little beyond structured fields.

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: 'walk downstream from an entity', plus the counterfactual variant. An agent can tell this is a graph traversal/impact tool rather than a search or retract tool. It does not name a sibling (e.g. quipu_path_cone, quipu_retract) to sharpen the boundary, so it stops short of a 5.

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

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

Gives one explicit usage cue: use remove=true when asking 'what would break if I removed this?', which is genuinely useful intent routing. It never says when NOT to use this versus the many sibling traversal/retract tools, and says nothing about prerequisites such as the entity IRI needing to exist or graph/namespace 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?

The annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds useful behavior beyond that: hash/vocabulary/attestation gates and exact-name merges defaulting off, but it does not explain what the destructive staging operation changes or what review entails.

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

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

Three compact sentences front-load the staging action and follow with the source constraint and merge warning. The phrasing is dense but efficient, with no filler; only the gate terminology is somewhat cryptic.

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

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

This is a destructive 11-parameter import operation with no output schema and 0% schema description coverage. The description covers the high-level staging concept but leaves most required parameter meanings, side effects, and the promotion boundary 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 11 parameters, so the description must compensate. It clarifies only a few semantics: source is copied from quipu_share, not a server path; attestation is a gate; and accept_exact defaults off. The remaining parameters, including actor, manifest, export_ntriples, shapes_turtle, queries_turtle, alignments_turtle, query_namespace, and replace_queries, remain 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: 'Stage a portable share' with hash, vocabulary, and attestation gates. It distinguishes the operation from a server file path and hints that promotion is a separate later step, though it does not name the sibling tool quipu_import_promote explicitly.

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

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

It provides context that member contents come from quipu_share rather than a server file path, and warns to review before promotion. However, it does not explicitly state when not to use this tool or name an alternative for the pre-import 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?

Beyond the destructive and open-world annotations, it discloses the gating constraint, that quarantine/resolution review cannot be bypassed, how target_graph scopes replacement only to the share's subjects, and that retire_from moves subjects out in the same transaction. The dry_run behavior is also explicit: report intended assert/replace/retire actions and write nothing.

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

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

Three sentences, front-loaded with purpose and gating, followed by behavioral constraints and parameter-specific effects. Every clause adds operational 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?

For a destructive, gated mutation tool with no output schema, it covers the essential safety constraints, graph scoping, retirement transaction, and dry-run reporting. It still omits actor semantics and normal return/failure signaling, leaving minor gaps for an agent composing it with 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 coverage is 0%, so the description carries the parameter burden; it clearly explains target_graph, retire_from, and dry_run semantics, including the transactional coupling. It leaves actor undocumented and only implicitly defines share_id as the staged share identifier.

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?

Starts with a specific verb and resource ('Promote a staged share') and scopes it to gated promotions, which separates it from generic import or knot-promotion siblings without relying on 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?

Explains the prerequisite clearly: only promote when existing promotion gates permit it, and it explicitly says quarantine or resolution review is not bypassed. It does not name a specific alternative sibling to use when those blockers exist, so it falls short of full 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?

Annotations already declare destructiveHint=true and openWorldHint=true, so the description should explain what gets destroyed; instead it says nothing about snapshot ownership replacing prior facts, retraction paths, or the fact that an unknown graph IRI is rejected rather than interned. The only added behavioral detail, 'optional SHACL validation', duplicates the shapes parameter and is already in the schema.

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

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

A single front-loaded sentence with no filler and the verb leading. It is efficient to the point of under-specification rather than verbose, which is a structural weakness but not a conciseness failure.

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, destructive, open-world write tool with no output schema, the description omits the consequences of the write (snapshot replacement/retraction, graph-must-exist precondition, validation failure behavior). The schema is complete, but the narrative an agent needs to choose and safely call 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 description coverage is 100% and the per-parameter descriptions are unusually rich (valid-time vs transaction time, snapshot ownership, graph registration, blank-node scoping), so the schema carries all parameter meaning. The description adds only the pointer to SHACL validation via the shapes parameter and no syntax, defaults, or interaction detail beyond that.

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

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

States a specific verb and resource ('Assert facts into the knowledge graph') plus a qualifier ('optional SHACL validation'), so an agent knows this is the write path. It does not distinguish itself from close siblings such as quipu_knot_stage, quipu_knot_promote, quipu_set, quipu_import or quipu_update, so the reader cannot tell which write tool to pick.

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

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

There is no when-to-use guidance at all: no statement of when to assert directly versus staging (quipu_knot_stage/quipu_knot_promote) or importing, and no prerequisites such as the target graph already existing. The parenthetical about validation is a capability note, not 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?

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds genuinely new behavior: the operation is atomic, it is asynchronous (pending is not completion), it is polled via the same upload_id, and existing validation gates still apply. It stops short of saying what a failed or partial promotion leaves behind, but the async/atomic disclosure is valuable beyond the annotations.

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

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

Three short sentences, front-loaded with the action, then the async polling caveat, then the validation constraint. The final sentence 'Existing validation gates remain authoritative' is somewhat vague about which gates and what failure looks like, but 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 destructive, open-world, async mutation with no output schema, the definition covers the polling contract but leaves gaps: no description of the returned status shape, no idempotency or retry guidance, and no statement of what 'validation gates' reject or how failures surface. Adequate to call correctly, thin for interpreting 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?

Schema coverage is 0% and the single upload_id has no description in the schema, so the description must carry the load. It does add meaning by implying upload_id identifies a previously staged upload and is reused across polling calls, but it never states the ID's origin or format explicitly.

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: 'atomic promotion of a staged snapshot upload', and clarifies the dual start/read-back mode. It doesn't name quipu_knot_stage or quipu_import_promote explicitly, but 'staged snapshot upload' plus 'upload_id' makes the pairing inferable.

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

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

Gives one concrete usage rule: when pending=true, poll the same upload_id rather than treating it as done. However, it never says when to choose this over quipu_knot_stage or quipu_import_promote, nor what preconditions must hold before promotion can start.

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

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

The annotations already declare destructiveHint=true and openWorldHint=true, so safety is partly covered. The description adds genuinely useful behaviour the annotations do not: replay is idempotent and changed bytes are refused, which tells the agent retries are safe but byte changes are not. It still omits return values, ordering constraints between parts, and whether a partial stage can be abandoned.

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 action, with no filler. The final fragment 'No file paths' is terse but earns its place as a hard constraint on the payload parameter.

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 12-parameter, 8-required mutation with no output schema, the definition covers the hashing and idempotency contract but not part ordering, how total_parts/total_bytes must agree, or what a successful stage returns. It is callable but leaves an agent guessing on multi-part sequencing.

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 12 parameters, so the description carries the burden. It meaningfully constrains content_hash and part_hash (must be exact sha256), upload_id (upload identity), and payload (inline, not a path), but leaves actor, graph, source, timestamp, total_parts, total_bytes, and part_number entirely unexplained.

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

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

The description states a specific verb and resource: staging a single immutable, numbered snapshot part. That is concrete enough to distinguish it from quipu_knot and quipu_knot_promote, though the sibling differentiation is implicit 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?

It gives operational preconditions (exact sha256 hashes, upload identity, no file paths) but no when-to-use or when-not guidance, and never points to an alternative sibling for a different workflow step. An agent must infer that this is the per-part staging call in a multi-part upload.

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 state readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — notably it never mentions that the optional `plan` flag computes a blast radius while writing nothing, which is the tool's most consequential behavioral nuance.

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 front-loaded sentence with zero filler; the filtering behavior is appended after the core purpose. Nothing is redundant.

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

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

For a zero-required-parameter read tool with a fully described schema and clear read-only annotations, the description is sufficient to call it correctly. The one gap is that the blast-radius `plan` capability — the reason to pick this tool for impact analysis — is invisible from the description alone.

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

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

Schema description coverage is 100%, so all three parameters, including the detailed `plan` and `risk_threshold` semantics, are fully documented in the schema. The description's only parameter claim is the status filter, which merely restates the enum.

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

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

"List schema evolution proposals" gives a specific verb plus resource, and the parenthetical enumerates the status values. It reads clearly against siblings like quipu_accept_proposal and quipu_reject_proposal, though it never names them to reinforce the distinction.

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

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

Usage is only implied: an agent can infer this is the read side of the proposal workflow, but the description never says when to prefer it over quipu_propose_schema_change or the accept/reject pair, nor does it hint at when the heavier `plan` analysis is worth requesting.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the safety profile is partly covered. The description adds genuine behavioral value by saying load materializes entailments and that loaded ontologies enforce constraints during later reasoning, but it never says that remove is the destructive branch or whether removal also discards materialized facts — the single most important consequence for an agent choosing an action.

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 taxonomy and no filler. The second sentence is dense but earns its place by explaining the downstream effect of loading; a per-action risk note would have been a better use of the space than the constraint enumeration.

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 four-parameter multi-action tool with full schema coverage and no output schema, the definition covers what each action does and what loading achieves. The remaining gap is return shape for list and the irreversibility of remove, which matters given destructiveHint=true.

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 every parameter is documented inline, including which are required per action (name for load/remove, turtle for load) and the default of action=list. The description adds no format or constraint detail beyond that, so the baseline 3 applies.

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

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

Names the resource (OWL ontologies) and enumerates the three concrete actions (load, list, remove), with a parenthetical clarifying that load means parse plus entailment materialization. An agent can distinguish this from generic query tools, though it never contrasts itself with nearby siblings like quipu_shapes, quipu_validate, or quipu_namespaces.

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 action list implies when each mode applies, and 'loaded ontologies enforce class hierarchy, disjoint-class constraints, and property characteristics' hints at why an agent would load one. But there is no explicit when-not guidance and no routing to alternatives such as quipu_shapes for shape validation or quipu_reason for inference.

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

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

Annotations already declare this a destructive, open-world write, so the description need not restate that. It does add genuinely new behavioral facts: atomic single-transaction semantics, provenance recording of reviewer and decisions hash, and idempotent replay returning outcome already-applied. However, it does not state permissions/auth requirements or the shape of the returned counts, which for a destructive tool leaves some transparency on the table.

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 'WRITE.' and the transactional payload, and the second sentence packs the refusal conditions and idempotency into one line. The refusal list is dense and slightly run-on, but no sentence is filler.

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

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

For a 7-parameter destructive tool with nested objects and no output schema, the description covers modes, transactionality, failure conditions, idempotency, and one return value (already-applied). Only the return payload beyond that single outcome and any authorization prerequisites remain uncovered.

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 cannot: fork and incoming+base are presented as mutually exclusive application modes, decisions must come from merge_decisions/resolve, and the reviewer is bound into the decisions hash. Those are semantic constraints not expressible in the JSON 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 ('Finish a share merge ... or a fork promotion') along with the two modes distinguished by the fork parameter, and names the upstream producers (merge_decisions, quipu_merge_resolve) whose output it consumes, so an agent can place it in the merge workflow without opening a sibling 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 terminal position in the workflow is clear ('Finish', 'the clean part plus every decided row'), and the description enumerates exactly the states in which it will refuse rather than write, which functions as a when-not-to-call list. It does not explicitly contrast dry_run with a real apply in prose (that lives only in the schema), so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint and non-destructive, and the description reinforces this with 'Writes nothing' and 'never sets a decision' - useful because the word 'merge' invites fear of mutation. It also discloses the read is bound to what was reviewed and that presentation output is the standard, unmodified view.

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 operation and its two modes, and no sentence is filler. But the phrasing is compressed to the point of strain - 'The conflicts of merging... bound to what was reviewed' is a fragment, and 'bound to what was reviewed' is vague about what binding means.

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 six-parameter, nested-object read tool with no output schema, the description covers the two input modes, both boolean modifiers, and the return shape when present is true. It leaves slot_scoped's v1/v2 semantics to the schema, which documents them adequately.

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%, but the description still adds meaning: propose populates evidence but never a decision, and present returns the specific {decisions, presentation, view} shape with the markdown unchanged. It also clarifies that base pairs with incoming as 'its parent share', which the schema only half states.

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

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

The description names the exact resource - conflict rows for a share merge (incoming + base) or a fork promotion into ROOT - and specifies the row shape (base/ours/theirs plus provenance). 'READ.' plus 'Writes nothing' separates it from the mutating siblings quipu_merge_apply and quipu_merge_resolve, though it never names them 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 rather than stated: 'it never sets a decision' and 'Writes nothing' signal this is the inspection step before resolving, and the two input modes are spelled out. However, there is no explicit instruction about when to pick a fork versus incoming+base, or when to move on to quipu_merge_resolve.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'touches no store' and adds behavior the annotations cannot: validation of the choice against the row, and the return shape {decisions, presentation, view}. It does not detail what happens on an invalid choice (error vs. no-op), which is the remaining 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?

Front-loaded with the core action and return shape, then choices, then the persistence pointer. Dense and telegraphic; 'value (with values)' is slightly cryptic, and the final 'Apply with...' sentence could have been merged more cleanly, but nothing is wasted.

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

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

For a 5-parameter tool with a nested object and no output schema, the description compensates well by naming the three return keys and stating the validation behavior. The only shortfall is not describing failure behavior or the meaning of 'presentation' and 'view'.

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 80%, so the schema already carries much of the load, but the description adds genuine meaning to the enum: 'ours, theirs, base, both (only within sh:maxCount), value (with values), defer', including a cardinality constraint on 'both' and the coupling of 'value' with the values array. 'row' and 'by' are left to 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: 'Record one choice on one row of a merge decisions file'. It also disambiguates from the sibling pair by noting the in-memory nature and pointing to quipu_merge_apply as the persisting step, so the agent knows this is the decide-step, not the write-step.

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 says 'touches no store. Apply with quipu_merge_apply', which routes the agent to the follow-up tool for persistence. It does not explicitly contrast with quipu_merge_decisions (the producer of the decisions file), so the full when/when-not picture is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true; "no writes or allocation" largely restates those hints. The genuinely non-obvious behavior — what "effective" resolution means (inherited vs. explicitly owned namespaces), whether results are tenant-scoped, and whether the list can be empty — goes unaddressed.

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 front-loaded sentence with the operation stated first and the scope constraint second; no filler. The trailing "no writes or allocation" clause is near-redundant with the annotations, which is the only wasted wording.

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

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

For a one-parameter read-only listing tool this is close to sufficient, but with no output schema the description could have indicated what a returned namespace entry contains or what "effective" means. As written, an agent knows it gets a namespace list but not how to interpret the 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?

There is a single optional parameter, action, with a one-value enum ("list") and 0% schema description coverage. The description's verb "List" implicitly maps to that enum value, so nothing is truly ambiguous, but no added meaning beyond the schema is provided.

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 ("List") and resource ("owner namespace registry"), so an agent knows this is a read of namespace metadata. However, "effective" is unexplained jargon and the description does not differentiate this from adjacent registry-like siblings such as quipu_datasets, quipu_shapes, or quipu_context.

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

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

"no writes or allocation" rules out a category of behavior but gives no when-to-use condition and names no alternative tool. An agent cannot tell from this text whether to call quipu_namespaces or quipu_datasets/quipu_shapes to discover available scopes.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so 'Read-only' merely restates them. The description does add real behavior beyond annotations — tombstone filtering ('asserted-and-not-tombstoned') and resolution order ('nearest wins') — but omits error behavior for unknown overlays and never explains the 'governed' mode, which indirectly conflicts with the blanket 'nearest wins' claim.

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

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

A single front-loaded sentence with no filler; the resolution rule is stated compactly. The bracket notation 'overlay > parent-branch-root' is cryptic enough that terseness costs some comprehension.

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

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

No output schema exists, so the description should convey what a 'composed view' actually returns (shape, ordering, size), which it does not. For a 2-parameter read tool with full schema coverage this is adequate but leaves the return value and the 'governed' precedence mode underspecified.

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 both parameters are already documented, and the description adds nothing per-parameter beyond reinforcing 'nearest'. The 'governed' enum value is left unexplained in both schema and description, and the 'parent-branch-root' chain notation is not defined.

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 ('Resolve') and resource ('an overlay's composed view'), and adds scope ('over [overlay > parent-branch-root]'). This is distinguishable from the write siblings quipu_overlay_create/quipu_overlay_write, though it does not explicitly contrast with quipu_acquire_composed, which sounds closely related.

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

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

No when-to-use guidance and no exclusions or alternatives. The agent must infer that this is the read path for overlays versus quipu_overlay_write, and nothing tells it when composition should be queried rather than using quipu_acquire_composed.

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

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

The description adds one genuinely non-obvious behavioral trait not present in annotations: the binding is 'bind-once', so the parent association is irreversible after registration. It also reassures that the committed layer stays untouched, which is meaningful context alongside destructiveHint=true. It does not cover what happens on duplicate/conflicting overlay IRIs, whether the overlay can be deleted later, or any permission requirements, so it only partially extends the annotation set rather than contradicting it.

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

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

Two tight sentences: the action and its bind-once constraint come first, then a short conceptual gloss on what overlays are for. No filler or repetition of the tool name. It could be marginally tighter, but every sentence contributes.

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

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

For a two-parameter creation tool with annotations and no output schema, the description covers the concept and the key immutability constraint. It leaves gaps an agent would care about before calling: error behavior on duplicate overlay IRIs, whether the overlay is addressable after creation, and lifecycle/cleanup. These are modest but real omissions for a bind-once registration operation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including the ROOT default for parent_branch. The description adds no IRI format guidance, no naming conventions for the overlay, and no clarification of the omit/null semantics beyond what the schema states. Baseline 3 is appropriate when the schema carries the parameter burden.

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 and resource: 'Register an overlay-class named graph' bound to a parent branch. It also defines what an overlay is (a scratch layer over the committed graph), which separates it conceptually from the graph-mutation siblings. It stops short of naming the adjacent tools (quipu_overlay_write, quipu_overlay_compose, quipu_graph_create) that an agent might 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?

Usage is implied through the workflow sketch: 'write hypotheses into an overlay, read the composed view, and the committed layer stays untouched.' That tells the agent the tool is the first step in a scratch-layer workflow. However, it never says explicitly when to prefer this over quipu_graph_create or the other overlay siblings, nor what prerequisites exist (e.g. whether the parent branch must already be committed).

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value by clarifying that tombstoning 'masks the parent branch's fact in the composed view without touching the committed layer,' which bounds the blast radius. It does not disclose idempotency, whether re-asserting an existing triple errors, or the result of the write, which matters for a mutating tool with no output schema.

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

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

Two sentences, no filler, with the core action front-loaded and the non-obvious tombstone semantics second. Every clause carries information the structured fields do not.

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?

All six parameters are schema-documented, so the input side is covered, and the op semantics are clarified. But with no output schema, the description should say what a successful write returns, and it omits preconditions (must the overlay exist? is the write transactional?) plus the meaning of the optional timestamp defaulting to now.

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 would be 3. The description exceeds it by explaining the semantics of the 'op' enum values — particularly that tombstone masks a parent-branch fact rather than deleting data — which the one-line enum description ('Overlay primitive to apply') does not convey. It also implies one triple per call, which the schema's flat shape alone does not make explicit.

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 ('Write one overlay primitive ... a triple in an overlay graph') and enumerates the three operations, so it is immediately distinguishable from base-layer writers like quipu_retract or quipu_set. It stops short of naming a sibling tool explicitly, so the differentiation is implied by the word 'overlay' rather than spelled out.

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 agent can infer this is the tool for overlay-layer edits, and the tombstone sentence hints at when masking is appropriate. There is no explicit 'use X instead when Y' guidance — nothing says when to prefer quipu_overlay_compose, quipu_overlay_create, or base-layer quipu_retract, nor whether the overlay graph must already exist.

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=true, destructive=false and openWorld=true, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: it distinguishes a genuine zero-match result from an unevaluable outcome, and states it refuses patterns it cannot compile — which tells the agent how to interpret failure rather than success.

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 'Golden paths' label and then the operation, with no filler. It is dense in domain jargon (gp-grammar/1, work-item topic, pruned candidate) but no sentence is wasted.

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

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

With no output schema, the description must gesture at return values, and it does via 'which past trajectories ... would have conformed' and 'how did their work items close'. Combined with the 0-matches vs cannot-evaluate distinction, an agent has enough to call it and read the result, though the shape of the report itself remains unspecified.

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

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

Schema coverage is 100%, so the schema already documents exemplar, omit and base_ns, making 3 the baseline. The description does add relational meaning by defining the candidate as the exemplar minus the omitted steps, but it says nothing about base_ns or the IRI form expected for omit entries.

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 (backtest) and a precise resource (a pruned candidate: exemplar trajectory minus omitted steps), plus the evaluation criterion (past trajectories sharing a work-item topic conforming to gp-grammar/1). It is clearly distinct from every sibling listed, though it never explicitly contrasts itself with nearby tools like quipu_path_cone.

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

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

Usage context is implied — you invoke this once you have an exemplar plus an omit list and want to know whether history would have conformed. There is no explicit 'use this instead of X' routing and no statement of preconditions (e.g. the candidate must be compilable, which is only hinted at via the refusal clause).

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 readOnly/non-destructive/open-world; the description goes well beyond them by explaining what each verdict means operationally — in-cone pruning requires a human Decision, out-of-cone is mechanically prunable, and cannot-evaluate is never silently prunable. It also discloses hard preconditions ('refuses trajectories with no steps or no falsifier-gated verification'), which is exactly the kind of failure-mode context an agent needs before calling.

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

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

Three sentences, front-loaded with the purpose followed by the verdict taxonomy and the refusal conditions; no sentence is filler. It is extremely terse and em-dash-heavy with dense domain jargon, which slightly taxes readability, keeping it off a 5.

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 takes on the return-value burden and does so by enumerating the three per-step verdicts and their pruning implications. Combined with the stated refusal preconditions and the fully documented input schema, an agent has everything needed to decide whether to call and how to interpret the result.

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

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

Schema coverage is 100%, so 'trajectory', 'via', 'hops' and 'base_ns' are already documented in the schema. The description reinforces the derivation-edge concept implicitly ('no derivation edges recorded') without adding syntax, defaults or format detail for any parameter, so the schema carries the load and baseline 3 is appropriate.

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

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

States a specific verb and resource ('compute the provenance cone of a trajectory') and immediately glosses it as 'which steps did its falsifier-gated verified result depend on', so the operation is unambiguous. It is also clearly distinguishable from neighbouring analysis tools like quipu_impact, quipu_path_backtest and quipu_explain by naming its input (a trajectory) and its output (per-step in/out-of-cone verdicts).

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

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

Usage context is clear: use it to find which steps are load-bearing for a verified result, and the refusal conditions ('no steps or no falsifier-gated verification') tell the agent when the tool will not apply. It stops short of explicitly naming alternatives (e.g. quipu_impact or quipu_path_backtest) or stating when NOT to reach for this versus those, so it is not a full 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description adds genuine context beyond them: determinism/reproducibility guarantees, that the verdict is returned UNSIGNED, that evidence_hash binds the result, and that a false evidence_probe downgrades 'unsatisfied' to 'unknown'. It does not cover cost, failure modes, or what happens with a non-existent policy IRI.

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

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

Three sentences, front-loaded with the core action and result type, which is good structure. However, it is dense with unexplained internal jargon ('committed-tier', 'aegis:claim', 'graph of record', 'Phase-0 verifier registry') and the signing sentence, while informative, could be tighter.

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

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

With no output schema, the description usefully describes the return value (Verdict with outcome enum and evidence_hash), which is the most important missing structured data. Gaps remain for a 7-parameter tool: tx, valid_at, and predicate_id are never discussed, and 'committed-tier' is never contrasted with other tiers.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema, including the $target placeholder, the policy-vs-claim alternative, and the evidence_probe unknown semantics. The description reinforces the $target binding and claim/policy duality but adds no new syntax, defaults, or precedence rules beyond what the schema states.

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: evaluates a governance Policy's aegis:claim (SPARQL ASK) over the committed graph and returns a Verdict with outcome and evidence_hash. The phrase 'signing + persistence is the Phase-0 verifier registry's job' implicitly separates it from quipu_verdict_verify, but no sibling is named explicitly, so an agent must infer the 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?

Usage is only implied by 'committed-tier evaluation' and 'any verifier re-running the same ASK'. There is no explicit when-to-use/when-not, no routing to quipu_ask for ad-hoc SPARQL or to quipu_verdict_verify for signature checking, and no stated prerequisites such as needing the policy already committed.

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

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

With annotations declaring readOnlyHint=false and destructiveHint=true, the description usefully explains the source of mutation: only 'louvain with persist:true writes quipu:memberOfCommunity facts (superseding any prior derivation)'. That 'supersedes prior derivation' clause is exactly the kind of destructive side-effect detail annotations cannot convey. It omits cost/performance characteristics and return shape, keeping it from a 5.

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

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

The algorithm list and the read-only caveat are front-loaded and the sentences are information-dense with no filler. The middle sentence ('Optionally restrict the projection...') is slightly redundant with the schema, and the algorithm enumeration makes sentence one long, but nothing is wasted.

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

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

For a 13-parameter, seven-mode tool with no output schema, the description covers mode selection, scoping filters, and the one mutating branch. The main residual gap is that it does not sketch what each algorithm returns (result shape, ranking format), which matters more given there is no output schema to fall back on.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters including defaults, enums, and the seeds-to-PPR switch. The description echoes a few of these (type/predicate restriction, seeds, persist) but adds no syntax, IRI format, or interaction detail beyond the schema; baseline 3 applies.

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

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

The description opens with a precise verb+resource ('Project the knowledge graph and run a graph algorithm over it') and then enumerates all seven algorithms with a short gloss for each (stats = node/edge counts, in_degree = most-referenced entities, louvain = modularity community detection). This makes it clearly distinguishable from siblings like quipu_stats, quipu_query, or quipu_impact 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 selection context at the algorithm level (personalized PageRank needs seeds; shortest_path needs from/to; louvain with persist writes facts), and states the default read-only mode. It stops short of naming alternatives or exclusions (e.g., when to prefer quipu_stats or quipu_cooccurrence over this), so it is strong context but not full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is largely covered. The description adds real value by stating the proposal does not take effect until explicitly accepted, which explains the gating behavior. However it says nothing about who may accept, what the submission returns, or that the optional migration executes as a single transaction on acceptance (that detail lives in the schema, not the description).

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 immediately followed by the most important constraint. No filler, no redundancy with the schema.

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

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

For an 8-parameter, 4-required mutation tool with a complex migration payload and no output schema, the description covers purpose and gating but omits the submission result, error/prerequisite conditions, and how the proposal is later consumed. The rich schema compensates substantially, so this is adequate rather than complete.

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

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

Schema description coverage is 100% and the migration parameter is documented in unusual depth (op vocabulary, expressions, transaction semantics), so the schema carries the parameter burden. The description adds no parameter-level meaning beyond the enum-ish parenthetical, making baseline 3 correct.

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

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

The description uses a specific verb plus resource ('Submit a schema evolution proposal') and enumerates the change kinds (new shape, class, property, ontology) that mirror the 'kind' enum, so an agent can map intent to tool. It stops short of naming siblings like quipu_accept_proposal or quipu_align_propose, so differentiation is inferred 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?

'Proposals require explicit acceptance before taking effect' implies the propose-then-accept workflow and hints at the follow-up tools, but no explicit when-to-use/when-not guidance or alternative routing is given. The agent must infer whether an ontology change belongs here versus quipu_load_ontology or quipu_align_propose.

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