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

With no annotations, the description carries real weight: it discloses the asynchronous pipeline (returns quickly, transcripts download in background, ready content is searchable immediately) and the cost/scope implication of full=True. It omits permission/auth requirements, deduplication behavior on repeat adds, and failure modes for an invalid handle.

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 the async behavior, then the full flag, then post-call instructions — a sensible order. Four sentences all do work, though "Tell the user the returned brain label and that more material keeps arriving" is agent-facing guidance that slightly blurs with the tool's own 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?

An output schema exists, so return values need not be explained, and the description covers the async model, the parameter tradeoff, and the follow-up message to the user. What is missing is edge-case behavior — repeat adds, invalid handles, and any rate or quota expectations for a long-running ingestion job.

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 must compensate and it does: handle is illustrated with both accepted forms, and full is defined precisely as "every video instead of the newest 30% plus the top winners" — semantics an agent could not infer from a bare boolean named Full.

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?

"Add a YouTube creator ... to the brain and start building it" is a specific verb+resource with concrete identifier formats (@handle or channel URL). It implicitly separates itself from the add_videos sibling by operating at channel level, though it never names that alternative 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?

The description makes the use case clear (onboarding a whole creator rather than individual videos) and explains the one branching decision, full=True vs the default 30% + top winners. It does not state when not to use it or what happens if the creator is already present.

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 no annotations to lean on, the description still carries real behavioral weight: it discloses that videos download and are analysed asynchronously in the background, and that dry_run provides a non-committal preview before the real call. It omits whether the addition is reversible, any batch limits, or whether the creator must already exist (add_creator).

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 and its scope, then the selection modes, then the dry-run workflow, then the async caveat. Dense and every sentence contributes new information despite the somewhat run-on second sentence.

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?

An output schema exists, so return values need no explanation, and the description covers the mutation's scope, selection options, and async processing. What remains unstated for a write operation with zero annotations is the failure mode (unknown creator, no matches) and whether params combine or override each other.

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 has to do the work and largely does: 'top' is clarified as most-viewed ordering, 'match' as title-word matching with a literal example ('protein diet'), and 'video_ids' as explicit selection. The remaining gap is the interaction between the modes (are they mutually exclusive or combined?) and the expected format of 'creator'.

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 ('Add more of a creator's videos to their brain') and immediately scopes it: the brain by default holds only the newest 30% plus top winners, with everything else sitting in the '<Name> - All Videos' note. That framing makes it clearly distinct from add_creator and search_brain without opening any 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?

Explicitly enumerates the three selection modes (title-word match with an example, explicit video_ids, top=N) and prescribes a concrete workflow: dry_run=True to preview matches, then call again to commit. It does not state when not to use it or name an alternative sibling (e.g. search_brain) for read-only lookup, so it stops short of the 5 bar.

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 no annotations, the description carries the full burden and does disclose the two important traits: default behavior is read-only inspection, and fix=True performs repairs but only 'what is safe', signaling partial rather than wholesale mutation. It omits runtime cost, whether repairs are reversible, and any permission requirements.

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 inspection scope is front-loaded and the mode switch plus usage trigger follow in the second sentence.

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?

An output schema exists so return values need not be described, and the description covers what it inspects, its modes, and when to invoke it. The remaining gap is operational: no sense of how long a full vault scan takes or how disruptive fix mode can be.

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 single parameter has 0% schema description coverage, but the description compensates by explaining fix=True explicitly enables repair while the default is check-only. That is the essential semantic an agent needs for this boolean.

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 (check the vault for problems) and enumerates the exact problem classes it detects: broken links, missing notes, failed videos, stale creators. The added fix mode and the pointer to search/status failures distinguish it cleanly from siblings like brain_status and search_brain.

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 concrete trigger: run it when search looks wrong or status shows failures, which implicitly routes the agent away from search_brain/brain_status toward this tool when those surface errors. It does not state when-not to use it or name the alternatives explicitly, so it stops 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?

With no annotations, the description carries the full burden. It does disclose useful behavior: a server starts on localhost, a URL is returned, and the graph updates live with Replay animation. It omits what happens if the graph is already running, whether the server persists or how to stop it, and any port or blocking behavior — meaningful gaps for a process-spawning tool.

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 result, then the user-facing instruction. The trailing clause about nodes popping in and Replay is partly flavor but conveys real runtime behavior, so it mostly earns its place.

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-parameter tool with an output schema, the description covers the action, the localhost URL return, and what to do with it. The only notable omission is repeated-invocation behavior (what happens if the graph is already running) and its relationship to pause_brain/resume_brain.

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 is nothing for the description to disambiguate; the baseline of 4 applies. The description does not need to explain any inputs.

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: start a live, animated brain graph served on localhost and return its URL. That is clearly distinct from siblings like brain_status (text status) or rebuild_brain (data rebuild). It stops short of naming a sibling explicitly, so it lands at 4 rather than 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?

Usage is only implied: an agent can infer this is for when the user wants a visual/animated view, and 'Give the user the link' is a concrete post-call instruction. There is no explicit when-not guidance or routing to alternatives such as brain_status or pause_brain/resume_brain.

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 no annotations, the description carries the disclosure burden and does well: it reveals that the tool reports background worker state, failure reasons, and an ETA, which tells the agent this is an informational read, not a mutation. It stops short of explicitly declaring it side-effect-free or stating whether querying has any cost.

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 core question and purpose, followed by the return contents and then the usage directive. 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?

An output schema exists so return values needn't be spelled out, and for a one-optional-param status check the description is nearly sufficient. The only real gap is the behavior when 'creator' is omitted.

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 'creator' parameter is nullable with a null default, yet the description never says whether omitting it returns global status or errors. The phrase 'how much of a creator is ready' only weakly implies that the parameter scopes the report to one creator.

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 question ('How complete is the brain?') and then enumerates exactly what the tool returns: label, percent built/searchable, percent analysed, worker state, failures with reasons, and rough ETA. This is clearly distinct from siblings like rebuild_brain, pause_brain, or brain_doctor.

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 states a concrete when-to-use: 'tell the user how much of a creator is ready before relying on search results.' That ties the tool to a real decision point. It does not, however, explicitly contrast with brain_doctor (also a diagnostic tool) or say when to prefer the status check over a rebuild.

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 no annotations, the description carries the full behavioral burden and does add real value by disclosing that results are per-creator with quotes, timestamp URLs, and transcript passages. It says nothing about whether creators must already exist in the brain, what happens with unknown or ambiguous creator strings, or whether this is an expensive multi-step operation.

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 with no wasted words: the operation and its result shape come first, the usage scenario second. Nothing is buried and nothing is repeated.

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?

An output schema exists, so return values needn't be spelled out, and the description still adds output flavor. But with zero annotation coverage and a completely undocumented input schema, the description leaves preconditions, failure modes, and parameter formats unaddressed for what is likely an expensive multi-creator retrieval.

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 neither parameter has a description, so the description must compensate. It implies 'topic' is a free-text subject and 'creators' is a multi-value set, but it never says whether creators are names, IDs, or handles, how matching works, or how many are allowed — a significant gap for the only two inputs.

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+resource ('Compare what several creators say about a topic') and even sketches the shape of the output (claims with quotes and timestamp URLs, plus matching transcript passages). It is clearly distinguishable from lookup-style siblings like search_brain or get_topic, though it never names an alternative to route against.

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?

'Use it to show where creators agree or disagree, and cite both sides' gives a concrete use case, so the intended usage is implied rather than left fully opaque. But there is no when-not guidance, no statement of prerequisites (do creators need to be registered first?), and no comparison against search_brain for the simpler single-topic lookup.

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?

No annotations exist, so the description carries the full load, and it does disclose meaningful behavior: results are ordered newest first, name resolution is loose across names and synonyms (a fuzzy-match caveat that matters), and output includes exact quotes plus timestamp URLs. It stops short of limits, pagination, or what happens when a topic has no verified claims.

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 what is returned, then matching semantics, then the citation requirement. Every sentence carries distinct information with zero 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?

An output schema exists, so explaining return values is a bonus rather than a necessity, and the description still characterizes the payload well for a single-parameter read tool. The one missing piece is disambiguation from search_brain, which would materially help an agent choose correctly.

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 must compensate, and it does: it supplies an example value ('Protein Intake') and explains the matching rule (names and synonyms matched loosely). Remaining unknown is case/format sensitivity of the input, but the essential semantics of the single parameter are conveyed.

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: returns everything verified about one topic, with an example topic and a precise description of the payload (claims, exact quotes, timestamp URLs). It is clear what the tool does, though it never names how it differs from its closest sibling search_brain or from list_topics.

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 payload description; the one explicit instruction ('Cite the timestamp URLs when you use a claim') governs downstream behavior, not tool selection. With 18 siblings including search_brain and list_topics, the absence of any 'use this instead of X when Y' guidance is a real gap.

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?

No annotations are provided, so the description bears the full disclosure burden. It reveals the payload fields but says nothing about read-only safety, ordering, pagination, or whether the list is exhaustive — meaningful for a tool billed as 'All topics'.

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 waste, with the returned content front-loaded and the use case second. Every sentence earns its place.

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?

An output schema exists, so return-value explanation is not required, and a zero-parameter read tool needs little else. Only ordering/scale behavior is left unstated, which is a minor gap given the low 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 schema defines zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The description correctly implies the call takes no scoping arguments.

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 the resource (all topics) and what each entry carries (claim counts and creators), which separates it from get_topic (single topic) and merge_topics. It stops short of naming those siblings explicitly, so the distinction is inferable 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?

'Use it to plan clean topic names and merges' gives one concrete use case, implying this is the discovery step before merge_topics or renaming. There is no when-not guidance and no explicit pointer to an alternative for other needs.

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 no annotations, the description carries the full burden and does real work: it discloses which data is mutated (claims, topic notes, video links, search index) and that old names survive as aliases rather than being deleted, which is the key safety fact. It stops short of stating reversibility, idempotency, or the effect of a failed run.

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 dense sentences plus an inline example, front-loaded with the operation and its shape; nothing repeats the schema. "Pause first" is terse to the point of being cryptic, but it is short enough that the efficiency outweighs the terseness.

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?

An output schema exists, so return values need no explanation, and the mutation surface is disclosed. But for a no-annotation, multi-entity rewriting operation, the description omits atomicity, error behavior, and the exact pause/resume procedure implied by "Pause first" — an agent could plausibly pause and never resume.

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 `groups` parameter is an undescribed nested object of arrays, so the description must compensate. The JSON example successfully conveys the key/value shape, but it leaves a real ambiguity: whether the map key must already exist (rename vs. create-on-merge) or can be a brand-new canonical name, and whether one source name may appear in multiple groups.

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 compound verb+resource ("Rename/merge topics") and immediately grounds it in a concrete JSON mapping, so the direction of the merge (new name -> list of old names) is unambiguous. It is clearly distinct from sibling readers like list_topics and get_topic, 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?

"Only existing names are used" and "Pause first" give an eligibility constraint and a prerequisite, which points the agent toward the pause_brain sibling. However, it never names pause_brain or resume_brain, never says when to prefer this over get_topic/list_topics inspection first, and gives no 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?

With zero annotations, the description carries the full burden and does reveal the storage medium (Me.md) and the dual read/write nature. However it never states whether 'updates' merges with or overwrites existing fields, what happens to unrecognised keys, or whether an empty profile is created on first write — material behaviours for a mutation path.

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, each doing distinct work: what is read, when to read it, and how to write. The field list is front-loaded and the example is placed last where it is most actionable.

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?

An output schema exists, so return values needn't be described, and the single optional parameter is explained with an example. The remaining hole is write semantics (merge vs replace) and error behaviour on unknown keys — modest for an optional single-parameter tool but still a real 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 0% and the only parameter is an untyped free-form object, so the description must compensate — and it does, giving both a concrete call form (updates={'goal': 'build muscle', 'days_per_week': 4}) and the list of valid keys through the field enumeration. It stops short of saying whether partial objects are merged or that arbitrary keys are rejected.

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 a specific verb+resource ('Read the user's profile (Me.md)') and enumerates the exact fields returned (goal, level, age, weight, injuries, equipment, days_per_week, diet, notes). It also discloses the secondary write capability via the updates example, so the agent understands this is a read/write profile endpoint rather than a pure reader — something no sibling tool covers.

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 states when to call it ('Read it before giving advice so the answer is personalised') and what to do about gaps ('ask the user for fields that are empty'), plus when to pass updates ('save new facts the user tells you'). No when-not guidance or alternative tool is named, but the tool's scope is narrow enough that none is needed.

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 no annotations, the description does real work: it discloses the transcript format, that topics and writing rules come back alongside the video, and the sentinel value video=None. The one gap is whether calling it advances a queue pointer or reserves the video — 'Repeat' implies progression but the state effect is never stated.

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 return contract and workflow, and the exhaustion rule lands last where it belongs. The 'YOU are the brain's reader' framing costs a clause of persona for little informational gain.

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?

An output schema exists, so return values need no prose, and the workflow is well covered. But an undocumented parameter on a stateful queue tool leaves an agent guessing about scoping and about whether a fetched video is consumed.

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 one optional parameter, creator, at 0% schema description coverage, and the description never mentions it. An agent cannot tell from either source whether creator filters the queue, is ignored, or changes the return shape.

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: it returns one video's transcript with [mm:ss] markers, plus the known topics and the card-writing rules. It also names the sibling it feeds into (submit_claims) and the exhaustion condition, so an agent can place it in the workflow without opening another 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 an explicit procedure: read the returned material, write the claims yourself, then call submit_claims, then repeat. It also states the stopping condition (video=None when nothing is left) and the reason to prefer this over an external AI key.

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 no annotations, the description carries the burden but discloses only that it halts background downloading/analysis. It does not say whether the pause is immediate or waits for in-flight work, whether it is idempotent, or that resume_brain is the way back. The output schema covers return values, so that gap is acceptable.

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 naming the action first and the prerequisite second. Every clause earns its place; there is no padding 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 zero-parameter control operation with an output schema, the description is nearly sufficient: it says what is paused and when to call it. It would be complete with a note on whether the pause blocks until settled and a pointer to resume_brain as the counterpart.

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; the baseline for a no-param tool is 4. Schema coverage being 100% with an empty properties object confirms nothing is left 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?

States a specific verb (pause) and the exact resource affected (background downloading/analysis), which is more precise than the bare name suggests. It also names two sibling tools that depend on it, making its role in the workflow concrete, though it doesn't explicitly say how it differs from resume_brain.

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 parenthetical gives a clear precondition: use before merge_topics or rebuild_brain. That is real when-to-use guidance rather than mere implication. It stops short of stating when pausing is unnecessary or harmful (e.g., if nothing is running), so 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?

With no annotations, the description carries the full burden. It discloses the operation's broad scope (every note) and a key precondition (pause first), but omits whether existing content is overwritten, whether the operation is reversible, how long it takes, or what permissions are required. Some behavioral context is given, but critical mutation safety details are missing.

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 with the core action front-loaded and the one prerequisite appended. No wasted words.

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?

An output schema exists, so return values need not be explained. However, for a bulk re-rendering operation with no annotations, the description is sparse on side effects, reversibility, and interaction with the pause/resume cycle—leaving meaningful gaps for safe 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?

The tool takes zero parameters, so there is nothing for the description to clarify. Baseline score of 4 applies for a parameterless operation.

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 ('Re-render') and resource ('every note') with concrete scope details (clean names, key points, topic links, dashboards). The bulk operation is distinct from sibling tools like search_brain or brain_doctor, though it doesn't explicitly name an alternative.

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?

Includes one concrete prerequisite ('Pause first') which is useful guidance, but does not state when to choose this tool over alternatives like brain_doctor, nor any when-not conditions. Usage is implied rather than fully specified.

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?

No annotations are provided, so the description carries the full burden. It discloses only that this resumes background work; it says nothing about whether the operation is idempotent, whether it requires the brain to be paused first, whether it is safe to call repeatedly, or what state it leaves things in.

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 short sentence with no filler, and the action is front-loaded. It is efficient, though the extreme brevity leaves no room for the routing or state information an agent would benefit from.

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?

An output schema exists, so return values need no explanation, and the zero-parameter schema is trivially complete. Still, for a lifecycle-control tool in a family with pause_brain and brain_status, the description should say what state must precede it and what happens on 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?

The tool takes zero parameters, so there is nothing for the description to clarify beyond what the empty schema already conveys. Baseline 4 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 ('Resume') and object ('background work'), which is clear enough to distinguish it from most siblings. It does not explicitly name pause_brain or brain_status as its counterparts, so the 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?

'after maintenance' is a lightweight when-to-use cue, implying it should follow downtime. However, it never states prerequisites (that work must first be paused), what happens if nothing is paused, or how it relates to pause_brain/rebuild_brain/brain_status.

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?

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the write target (outputs/) and that the file becomes visible in Obsidian, but says nothing about collision/overwrite behavior when a title already exists, whether it returns a path, or any permission requirements.

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 with no filler, and the primary action plus destination are front-loaded before the secondary guidance about sources.

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?

An output schema exists so return values need no explanation, and the destination is covered. However, for a write tool with zero annotation coverage and zero schema descriptions, the description should still address overwrite semantics and what 'markdown' content is expected.

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 3 parameters, so the description must compensate. It does explain the purpose of 'sources' (timestamped URLs / video titles relied on), which is genuinely additive, but leaves 'title' and 'markdown' (format, whether frontmatter is expected) 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?

States a specific verb and resource ('Save a finished plan, summary or answer') and pins the destination ('into the vault (outputs/)') plus the user-visible outcome in Obsidian. No sibling tool does this, so an agent can route to it unambiguously.

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?

'Always save plans with this tool' gives an explicit trigger condition, and the second sentence tells the agent what to include in sources. It lacks any when-not guidance or alternative path, but the positive usage rule is unambiguous.

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 no annotations at all, the description carries the full behavioral burden and does so well: it discloses the return shape (short snippets, each with a timestamp URL), mandates citations of title + URL, and warns that brain_completeness below 100% means results may be missing videos. It omits operational traits like rate limits, error behavior, or whether results are ranked, so not 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?

Four short sentences, front-loaded with the action and the imperative to use it before answering from memory. Every sentence adds either a directive, a citation requirement, or a data-quality caveat — nothing is padding.

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?

An output schema exists, yet the description still usefully explains the snippet/URL citation contract and the brain_completeness caveat, which the schema alone would not convey. The main omission for a three-parameter retrieval tool with no annotations is any statement about result count (limit) or missing-field 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 compensate — and it does for two of three parameters: query should be plain words (illustrated with 'protein per day for muscle gain') and creators takes a slug list (illustrated with 'jeremy-ethier'). The limit parameter (default 8) is never mentioned, leaving one 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?

States a specific verb and resource pair — search creators' transcripts and verified claims — which an agent can immediately distinguish from siblings like compare_creators, get_topic, and brain_graph. The parenthetical framing as a pre-answer lookup step further pins down what the tool is for.

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 to call it BEFORE answering from memory, which is a strong, actionable trigger. It also gives narrowing guidance (creators=['jeremy-ethier']) and a query-phrasing tip. It stops short of naming when to prefer a sibling such as compare_creators or list_topics, so no explicit exclusions.

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 no annotations, the description carries the burden and does well: it discloses the exact-match validation, that non-matching items are silently dropped, and that the result reports how many were kept. It omits duplicate handling (does resubmitting replace or append claims?) and any auth/permission constraints.

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 payload shape is front-loaded and every clause earns its place — the quote-length range and the exact-copy rule are exactly what an agent needs to avoid a silent drop. Slightly dense as a single run-on block, but 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?

An output schema exists, so return values are covered, and the description still adds the one return-relevant fact (kept-count). Combined with the full payload specification and the cross-reference to 'reuse known topics' (sibling 'list_topics'), an agent has enough to call this correctly.

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 item object is otherwise opaque ('additionalProperties: true'), so the description's per-field breakdown (claim, quote with 6-40 word exactness rule, t as mm:ss, topic Title Case reuse, kind enum) is essential and well done. The 'video_id' parameter is left undocumented, presumably assumed obvious.

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 and resource: 'Add your knowledge cards for a video'. This is clearly distinct from the sibling 'add_videos' (which registers videos rather than extracted claims), though the distinction is implied rather than stated 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 — an agent infers this is the step after 'next_video_to_analyse' and possibly after 'list_topics'. There is no explicit when-to-use, no prerequisite (e.g. must the video be in an analysis session?), and no statement of what to do if a quote is rejected.

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 no annotations, the description carries the full burden and does disclose key behavior: results are ranked by views, existing brain creators are filtered out, and no write occurs without user selection. It omits how many suggestions are returned and that this likely queries an external service (latency/quota), which matters for a discovery 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?

Two sentences, zero filler, with the discovery behavior front-loaded and the follow-up action second. Every clause (ranking, exclusion, user gate) earns its place.

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?

An output schema exists, so return-value explanation is unnecessary, and the description covers ranking, filtering, and the next step. The remaining gap is topic-parameter semantics and expected result volume.

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% for the single 'topic' parameter, so the description must compensate; it only implies the parameter by saying results are 'for a topic'. It does not say whether 'topic' is free text, must match list_topics output, or how matching/normalization works.

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 ('Find YouTube channels') plus the ranking rule ('ranked by views in search results') and a scope constraint ('excluding creators already in the brain'). This clearly separates it from siblings like add_creator (mutation) and search_brain (existing inventory).

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 explicit downstream routing: show results to the user, then call add_creator only for the ones they choose — a clear sequencing and human-confirmation rule. It does not address when *not* to use this tool (e.g. checking existing creators via search_brain/list_topics), leaving one gap.

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 no annotations, the description carries the full burden and does well: it discloses that items are queued (a side effect), that processing is asynchronous ("appears in search as it finishes processing"), and that the operation is cheap and auto-scheduled daily. It omits what happens with an unknown creator or how many videos might be queued, so it stops just short of full 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?

Two short sentences, front-loaded with the action and scope, with the cost and async behavior following. No filler, though the second sentence mixes two unrelated facts (cost/schedule and search visibility) somewhat loosely.

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?

An output schema exists so return values need no explanation, and the async processing caveat is covered. The remaining gap is the creator identifier format, which matters for correct invocation of a 0%-coverage parameter.

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% for the single nullable parameter, so the description must compensate. It does explain the null case ("or all of them"), but never says what form the creator value takes (name, handle, ID, URL), leaving the key ambiguity unresolved.

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 and resource: check a creator (or all) for new videos and queue anything new. This is clearly a polling/refresh operation, which implicitly separates it from add_creator and add_videos, but the siblings are never named so the differentiation stays inferential.

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?

"Cheap and quick; it also runs automatically about once a day" implies manual calls are optional and low-cost, which is useful context. However, it never states when a manual refresh is warranted versus using add_videos or add_creator, and gives no exclusion conditions.

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