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

The description adds meaningful context beyond annotations: it reveals an external dependency (OPENAI_API_KEY), clarifies the side effect of saving to staging, and states 'Does not publish media.' These details complement the annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

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 two sentences long, front-loaded with the core action, and every clause adds relevant information. No redundancy or 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?

For a tool with 11 parameters and no output schema, the description covers the core purpose, key side effects, and dependencies. It could elaborate on failure modes or return format, but the strong schema and annotations mitigate the need for more detail.

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 already provides detailed descriptions for all 11 parameters (100% coverage), so the description adds limited value for parameter semantics. The mention of returning a local path and manifest metadata provides slight extra context but does not significantly enhance understanding of individual parameters.

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's function: generating an image via OpenAI, saving it to Context Bridge staging, and returning a local path plus manifest metadata. It also differentiates from siblings by explicitly noting it does not publish media, distinguishing it from publishing/registration tools.

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 context on what the tool does and highlights the environment requirement (OPENAI_API_KEY). It implies when to use this tool versus publishing tools, but does not explicitly name alternative siblings like register_image_asset for registering existing assets, leaving a small 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?

Annotations indicate not read-only, idempotent, and not destructive. The description adds valuable context that this is draft-only and performs no Homebase repo writes, clarifying the intended behavior beyond the raw annotations. It does not contradict any annotation.

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 are packed with essential information: what it creates, for whom, and that it's draft-only. No fluff or redundant wording.

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 simple 2-parameter tool with no output schema, the description is nearly complete. It explains the purpose, scope, and behavior, though it could explicitly state the return format (though response_format param implies 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 100%, so both parameters (staged_chat_id, response_format) are already documented. The description adds no further parameter-specific detail, so baseline 3 is appropriate.

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 creates a staged Homebase markdown draft and suggested canonical path for one staged chat. It uses a specific verb ('Create') and resource ('staged Homebase markdown draft'), and the context 'one staged chat' distinguishes it from sibling tools like propose_notion_page or stage_chat.

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 implies when to use the tool: for a staged chat and when only a draft is needed, with 'Draft-only; no Homebase repo writes' clarifying scope. However, it does not explicitly name alternatives or exclusion criteria, so it stops short of a 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?

Annotations include idempotentHint=true and destructiveHint=false; description adds crucial context that this is draft-only with no Notion API calls or page mutations, clarifying that any side effects are local payload creation only. This goes beyond what annotations alone convey.

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?

Single concise sentence, front-loaded with the verb and purpose. No wasted words, and it includes the key safety qualifier ('Draft-only') in the same 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?

Given the tool's moderate complexity and full schema coverage, the description conveys the main purpose and critical constraints. It lacks an explicit statement of the return value, but the response_format parameter implies the output format, and the tool name/content fill the 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 descriptions cover both parameters (staged_chat_id and response_format) at 100%, so the description doesn't need to add parameter details. It references 'one staged chat' which aligns with staged_chat_id but adds no new semantic meaning.

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 states a specific action ('Create a staged Notion payload') with a clear resource and scope ('for one staged chat'). It also distinguishes from siblings by indicating draft-only and no API calls, differentiating from propose_homebase_note.

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?

Provides clear context: it should be used when you have a staged chat and want a payload. However, it does not explicitly mention when not to use it or alternatives like propose_homebase_note, so it falls short of full exclusion 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?

Annotations already cover readOnly=false, destructive=false, and idempotent=true. The description adds a useful constraint ('Does not publish media') but does not explain the actual side effects of staging (e.g., where records are stored, whether files are copied) or any prerequisites. It adds some context but not rich behavioral transparency.

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 two sentences, front-loaded with the action ('Stage image-generation artifacts'), and every clause earns its place. The second sentence provides a clear boundary without 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?

With 7 parameters, 2 enums, and no output schema, the description is minimal. It covers the purpose and a key constraint but omits operational context such as how response_format affects output, what 'staging' entails (e.g., database write, file copy), and when to use it in a workflow. It is adequate but has clear gaps.

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%, so baseline is 3. However, the description introduces the ambiguous phrase 'optional local copied asset' that does not map cleanly to any schema parameter (likely referring to 'source' or 'suggested_homebase_folder'), and it only lists a subset of fields. This could confuse an agent selecting parameters, and the description adds little value beyond the schema.

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's purpose: to stage image-generation artifacts by recording prompt, source chat, usage-rights note, and optional local copied asset. It explicitly differentiates from publishing by stating 'Does not publish media,' which distinguishes it from sibling tools like generate_image_asset and propose_notion_page.

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 implies use for recording/staging image artifacts before publication, but it does not explicitly state when to use this tool versus alternatives such as generate_image_asset or propose_notion_page. It gives clear context ('stage', 'does not publish') but no explicit alternatives or 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?

Annotations already declare readOnlyHint and idempotentHint, and the description adds that the tool is private and returns specific fields, which is useful behavioral context beyond what annotations provide. There is no contradiction, and the description enriches understanding of the search scope.

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 two concise sentences, front-loaded with the core action ('Search private Context Bridge staging records') and includes only necessary detail about return values. Every word 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 simple filtered search tool with no output schema, the description adequately conveys purpose and return structure. It complements the well-documented schema by explaining what is returned, making the tool understandable in context.

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 descriptions cover 100% of parameters, so the schema already fully explains all four parameters (limit, query, offset, response_format). The description adds no additional parameter-level detail, so the baseline score of 3 is appropriate.

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 verb 'Search' and the resource 'private Context Bridge staging records', and specifies the returned fields (chat IDs, titles, summaries, draft paths). This distinguishes it from sibling tools like stage_chat or summarize_thread, which create or process context.

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 clearly indicates this tool is for searching staged records and is read-only, providing context that differentiates it from sibling tools that create or modify data. However, it does not explicitly mention when not to use it or name specific alternatives, so it falls short of a full explicit exclusion.

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?

Annotations already indicate write (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds valuable context about reading local files, redaction, classification, and the staging-only write scope, which enriches the agent's understanding without contradicting annotations.

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 two sentences, front-loaded with the core action, and contains no redundant or superfluous information. Every phrase contributes to understanding the tool's function and scope.

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 6 parameters, no output schema, and complexity around redaction/classification, the description covers the main workflow and exclusions. It does not elaborate on classification details or artifact specifics, but with good annotations, this is sufficiently complete for an agent to select and invoke the tool 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 100%, so all parameters are well documented in the input schema. The description gives a general overview but does not add specific parameter details beyond what the schema already provides. It meets the baseline but does not go further.

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 reads local chat export files, redacts sensitive values, classifies them, and writes staging artifacts. It explicitly distinguishes itself from siblings by noting it does not write to Homebase or Notion, making the purpose 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 context for when to use the tool: for staging chat data without writing to Homebase or Notion. It implies when not to use (when final writes are needed) and explicitly mentions the exclusion. However, it does not name alternative sibling tools explicitly, so it falls short of a 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds 'deterministic' (consistent with idempotency) and enumerates the return contents (summary, action candidates, risk notes), providing behavioral detail beyond the safety annotations.

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 with a clear verb and object. Every word earns its place; there is no redundancy or 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?

With no output schema, the description compensates by listing the three return components (summary, action candidates, risk notes). Combined with good annotations and simple 2-param schema, it is adequately complete for a read-only tool, though it doesn't describe output formatting details beyond the response_format 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?

The input schema has 100% coverage with descriptions for both staged_chat_id and response_format. The description does not add new parameter-level meaning, only reuses 'staged chat ID' in the text, so it meets the baseline but adds no extra value.

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 verb 'Return' and specifies the exact resource: 'deterministic summary, action candidates, and risk notes for one staged chat ID.' It is distinct from sibling tools like stage_chat (which likely creates) and propose_homebase_note (which proposes content).

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 context: it operates on a 'staged chat ID' from stage_chat or search_context, implying it is used after those tools. However, it does not explicitly name alternatives or state when not to use it, stopping short of full exclusion guidance.

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