nest_promote

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

With no annotations, the description carries full responsibility and excels. It discloses what is never read (fragment content, filenames, person names), what dry_run does (returns atoms without writing), and the subject_id consent seam (requires a verified grant, is opaque, never written, and logged to the disclosure chain). This goes far beyond basic safety and side-effect disclosure.

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

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

The description is front-loaded with the primary purpose, then logically flows into dry_run and subject_id. Each sentence contributes valuable information, and the paragraph breaks aid readability. It is somewhat lengthy but justified given the need to explain consent mechanics and safety guarantees.

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 thoroughly explains the tool's behavior, dry-run semantics, and the subject_id consent seam. It does not specify the return value for dry_run=False (beyond ingesting), nor does it mention app_id/db_path or error conditions. Given the tool's complexity and lack of output schema, there are minor gaps, but the overall context is strong.

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 description adds substantial meaning for dry_run and subject_id, explaining their behavior and constraints. However, it completely omits app_id (the only required parameter) and db_path. With 0% schema description coverage, the description should explain all parameters to compensate; it covers only two of four, leaving key required context 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 opens with a specific verb+resource: 'Promote a Nest's STRUCTURE into the knowledge base.' It clearly distinguishes this from siblings by emphasizing structure-only atoms (counts, category names, redacted secret kinds) and explicitly contrasting with knowledge_ingest's core write. The scope is precise and unambiguous.

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

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

The description provides clear contextual usage: promote a Nest's structure, use dry_run for safe inspection, and use subject_id for non-owner life-dumps. It hints at alternatives by referencing the same write path as knowledge_ingest, but does not explicitly name other sibling tools or state when not to use this tool. Still, the guidance is substantive and actionable.

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