quipu_acquire

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.