brain_ingest

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tempId mechanism ('the server substitutes real identifiers'), how a parent can be a tempId or an existing UUID ('how a new branch grafts onto what the brain already holds'), and the schema adds deduplication-on-by-default (making re-runs safe), order independence, and maxItems 200. These are non-obvious behaviors an agent must know.

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 tightly scoped paragraphs: the first states purpose and when to use, the second explains the tempId/parent mechanism, and the third offers search-first guidance. Every sentence earns its place—there is no repetition of schema details or filler. The front-loaded verb and resource make the tool's purpose immediately clear.

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?

Given the tool's complexity (bulk write with tempIds, links, tags, deduplication, and no output schema), the description provides complete context for selection and invocation. It covers the purpose, prerequisites (brainId from brain_list is stated in the schema), the tempId workflow, the deduplication safety, and the recommended search-first sequence. No essential guidance is missing.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. For example, it defines tempId as 'arbitrary labels you invent yourself', explains the parent field's dual nature (tempId or existing UUID) in the context of grafting, and clarifies that links are 'extra links on top of the hierarchy.' The deduplicate parameter's default behavior is also described, enabling correct invocation choices.

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: 'Writes a whole structure of thoughts, links, notes and tags in a single call.' It clearly distinguishes itself from the one-by-one siblings by emphasizing batch scope and explicitly contrasts with creating thoughts individually ('creating them one by one at that volume is slow and breaks halfway'). This leaves no ambiguity about what the tool does.

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 explicit when-to-use guidance: 'Call it once you have decomposed some material...' and warns against using the alternative (one-by-one creation). It also provides a concrete 'search first' rule: 'Search with brain_search first: some of the thoughts may already exist, and linking to them beats creating duplicates.' This names the alternative tool and states the precondition.

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