nest_promote

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

The description explains that subject_id is opaque and never written to the KB, dry_run is safe to inspect, and committed promotions are logged to a disclosure chain. This adds significant behavioral context beyond the annotations, which are sparse (only readOnlyHint, openWorldHint, destructiveHint).

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 moderately lengthy but each sentence adds value, explaining the data source, dry_run behavior, subject_id purpose, and logging. It could be slightly more concise by integrating the subject_id explanation more tightly, but it is well-structured.

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

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

The description fully compensates for the lack of an output schema and low schema coverage. It covers the tool's behavior, parameters, edge cases (non-owner dumps, dry_run), and security considerations. For a tool with 4 parameters and no output schema, this is complete.

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

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

Schema description coverage is 0%, so the description must carry all parameter semantics. It explains skips_read resolves lifecycle issues, forest entangles when the read lands, and last_epoch is required to perform certain housekeeping. However, app_id and db_path are not explicitly described, which is a minor gap.

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

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

The description clearly states the tool promotes a Nest's structure into the knowledge base, specifying the source (bridge.build_bridge), what is promoted (structure-only atoms), and what is excluded (fragment content, filenames, person names). This distinguishes it from other tools like gap_promote and kb_promote by focusing on nest structure promotion.

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 provides explicit guidance on when to use dry_run=True vs False, and explains the subject_id parameter's purpose for non-owner life-dumps. It also names the underlying write tool (knowledge_ingest) and implies alternatives like kb_promote by specifying this is for nest structure only.

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