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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It explains the short-circuit behavior (clarificationNeeded: false), the structure of each question (suggested_answer, options, dimension), and the effect of the force flag. It also notes that passing a category skips questions about category/platform. This is comprehensive for a non-destructive 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?

The description is thorough but not overly verbose. It front-loads the core purpose and then expands on behavior and structure. Every sentence contributes useful information. Could be slightly more compact, but it remains efficient.

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 9 parameters (1 required), high schema coverage, and no output schema, the description provides complete context. It explains the tool's behavior, response format, short-circuit logic, and ties to sibling tools (optimize_prompt). No critical gaps are present.

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 89%, so the schema already documents most parameters. The description adds value by explaining the structure of the generated questions (suggested_answer, options, dimension) and the effect of force: true. It also clarifies how category can skip certain questions. These details enhance understanding 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: 'Given an ambiguous draft prompt, return 1–3 targeted clarifying questions instead of guessing.' It specifies the verb (return), resource (clarifying questions), and distinguishes from alternative behaviors (short-circuiting). This is specific 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 explicit when-to-use and when-not-to-use guidance: it explains the short-circuit behavior when the analyzer is highly confident and the prompt is non-trivially long, and mentions pipelining in front of optimize_prompt. It also describes the force parameter for overriding the short-circuit. This clearly differentiates usage contexts.

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 full burden. It details the pipeline flow, short-circuit behavior, branch conditions, and auto-revise loop. It mentions stages as an audit log and cost limits (max_iterations). However, it lacks disclosure on potential side effects, auth needs, or rate limits.

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 a single paragraph that front-loads the purpose and then explains behaviors. It is dense but efficient for the complexity. Could be improved with bullet points for scannability, but remains concise.

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 25 parameters, 40% schema coverage, and no output schema, the description falls short. It does not describe the output structure (e.g., final_prompt, stages) nor error conditions. Many contextual parameters (session_id, file_path, etc.) are undocumented, leaving gaps for an AI agent.

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 40%, so the description must compensate. It adds value for core parameters (pre_clarify, sources, post_critique, auto_revise, max_iterations, model overrides) explaining their behavior. However, many parameters (category, platform, mode, file_path, etc.) are not described, relying solely on 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 runs the canonical ClarifyPrompt pipeline in one call, covering clarify, ground/optimize, critique, and auto-revise. It distinguishes from sibling tools by explicitly noting it replaces orchestrating five round-trips. The branching based on sources (ground vs optimize) is also specified.

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 explains when to use the tool: when wanting the four-tool happy path without orchestrating. It covers short-circuit behavior for pre_clarify, branching conditions, and auto-revise. However, it does not explicitly state when not to use it (e.g., for fine-grained control, use individual tools), though this is implied.

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 fully discloses key behaviors: it returns per-dimension rationale, concrete suggestions, an overall score, and a verdict. It explains that when below 'revise_threshold' (default 7.0), it returns an 'improvedPrompt'. It also mentions custom criteria and skip_rewrite. It does not discuss side effects or costs, but for a critique tool the disclosure is thorough.

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 core action and results, then explains use cases and special parameters. Each sentence adds value without redundancy. It is appropriately sized for the complexity—neither too terse nor verbose.

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 has 11 parameters and no output schema, the description covers the main function, return values (rationale, suggestions, score, verdict, improvedPrompt), and key optional parameters. It does not explain every parameter, but the core functionality is well-documented. The output structure is sufficiently described for an agent to understand what to expect.

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 45%, so the description must add meaning. It does for key parameters: 'prompt' (candidate prompt), 'original_prompt' (intent preservation for optimized versions), 'criteria' (custom dimensions), 'revise_threshold', and 'skip_rewrite'. However, parameters like 'cwd', 'file_path', 'file_language', 'file_excerpt', and 'user_locale' are not explained in the description, leaving gaps.

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 starts with 'LLM-as-judge for a prompt', clearly stating the tool's core purpose. It specifies it scores 0–10 across dimensions, returns rationale, suggestions, overall score, and a verdict (accept/revise/reject). The name and verb 'critique' align, and the description distinguishes from siblings by mentioning pre-flight, postmortem, and A/B testing use cases.

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 explicitly states when to use the tool: 'pre-flight', 'postmortem', or 'to A/B-pick the best of N optimization variants'. It also advises passing 'original_prompt' when critiquing an optimized version. However, it does not mention when not to use it or provide explicit alternatives among the sibling tools.

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. The description does not explicitly state that the tool is read-only or has no side effects, but it describes the output in detail (candidates, selections, reasons, token usage). For a read-only explanation tool, this is adequate but leaves some ambiguity about mutability.

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: the first states the main function, the second adds detail and a use case. It is front-loaded with no extraneous information.

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 no output schema, the description adequately explains the return content (candidates, selection status, reasons, token usage). Parameters are mostly covered, and the use case is clear. Minor omission: doesn't specify if the tool queries stored data or triggers a new analysis.

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 50%: 'optimization_id' has a clear description; 'lookback_days' is only described via constraints. The tool description explains the main purpose but does not elaborate on 'lookback_days' beyond the schema, so it partially compensates for the coverage 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 renders a human-readable explanation of curation decisions, specifying the resource (Context Curator's decisions for an optimization) and action (render explanation). It distinguishes from siblings like 'get_trace' or 'inspect_context' by focusing on curation decisions.

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 a clear scenario: 'Use this when an output felt off and you want to understand which grounding sources the engine chose.' It implies a debugging use case but does not explicitly list when not to use it or compare to alternatives.

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 full burden for behavioral disclosure. It only reveals the default lookback period and that the trace includes system prompt and output. It does not mention whether the operation is read-only, error handling, rate limits, or permission requirements, leaving significant gaps.

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 extremely concise with two sentences, front-loading the primary action and content, then adding the temporal scope. No unnecessary words or repetitions.

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 simplicity (2 parameters, fetch operation), the description provides enough context: what it returns (full trace, system prompt, output) and default behavior. However, it lacks details on return format or error handling, which are not critical but would improve completeness. Since there is no output schema, the description could be slightly more explicit.

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. It adds meaning by stating the 'id' is an optimization ID and the 'lookback_days' defaults to 7. However, it does not explain the exact format of the id or provide further context for the parameters beyond what the schema already conveys (e.g., exclusiveMinimum, maximum).

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 'Fetch', the resource 'full trace for an optimization ID', and includes what it contains ('system prompt + output'). It also provides the default lookback period, which helps differentiate from sibling tools like list_traces.

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?

No explicit guidance on when to use this tool versus alternatives, such as list_traces or inspect_context. It does not mention prerequisites, exclusions, or scenarios where another tool would be more appropriate.

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?

Discloses key behaviors: sources are pinned at highest priority, tracked individually in trace, capped at 4000 chars, requires at least one non-empty source, and error behavior. While no annotations exist, it covers most relevant aspects for decision-making.

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?

Every sentence is purposeful: states purpose, priority, usage guidance, constraints, and error behavior. No redundant or filler content. 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?

For a complex tool with 15 params and no output schema or annotations, the description covers core functionality, usage scenario, and important constraints. Some optional params are left to schema descriptions, but the essential context for selection and invocation is present.

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 some context beyond the schema (e.g., priority over project rules, error behavior), but schema coverage is only 13%, and many optional parameters remain unexplained. The description compensates partially for the required params but not fully for all 15.

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 optimizes a prompt against explicit grounding sources, distinguishes it from optimize_prompt by mentioning error behavior and priority, and provides specific examples of sources (spec, transcript, RFC, etc.).

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 tells when to use this tool ('when you want the rewrite to cite specific material') and when not to ('will error rather than silently fall through to optimize_prompt'), providing clear alternatives.

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?

Given that no annotations are provided, the description carries the full burden. It discloses that the tool is non-destructive ('without running optimization') and what it returns, which is sufficient for a preview 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?

The description is two sentences long with no superfluous information. It front-loads the core action and provides clear, efficient context.

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 8 parameters, no output schema, and no annotations, the description is too brief. It lacks details on parameter usage, output format, and behavioral edge cases, making it insufficient for complex calls.

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 does not explain any of the 8 parameters despite 0% schema description coverage. It adds no value over the schema, leaving the agent to infer meaning from parameter names alone.

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 uses a specific verb 'Preview' and identifies the resource 'ContextBundle' with details on its contents. It explicitly distinguishes itself from the sibling tool 'optimize_prompt' by noting that it runs without optimization.

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 states it returns the same bundle as optimize_prompt would assemble, implying it is for previewing. However, it does not explicitly state when to use this over alternatives or provide 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?

Without annotations, the description carries the burden of behavioral disclosure. It accurately implies a safe read operation but omits details such as ordering or error handling.

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 a single, front-loaded sentence with no extraneous words, efficiently conveying the tool's purpose.

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 simplicity (no parameters, no output schema), the description is largely complete. However, it could mention the read-only nature for completeness.

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?

With zero parameters, the baseline is 4. The description adds no parameter info because none exist, but it implies output structure without an output 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 lists prompt optimization categories with platform counts, using specific language that distinguishes it from sibling tools like list_platforms or list_modes.

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?

No guidance is provided on when to use this tool versus alternatives; no context or exclusion criteria are mentioned.

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 clearly indicates a read-only listing operation without side effects, which is adequate for a simple list tool. However, it could mention if any authentication or context requirements exist, but none are needed here.

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 sentence, no wasted words, front-loaded with the action.

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 has no parameters and no output schema, the description fully captures what it does. It is complete for a simple list operation.

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 has no parameters, and schema coverage is 100%. Baseline for 0 parameters is 4. The description does not need to add parameter info.

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 lists available output modes for prompt optimization, using specific verb and resource. It distinguishes from siblings like list_categories and list_platforms by specifying 'for prompt optimization'.

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?

No explicit guidance on when to use this tool versus alternatives like list_categories or list_packs. Usage is implied—when you need output modes for prompt optimization—but no exclusions or comparisons are provided.

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 provided, the description carries the full burden for behavioral disclosure. It only states the read operation ('list') but lacks details on permissions, rate limits, side effects, or result format.

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 a single sentence of 10 words, front-loaded with the action and resource, containing zero superfluous information.

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 one optional parameter and no output schema, the description minimally covers the tool's purpose. However, it lacks usage guidance and behavioral details, leaving gaps for effective invocation among 22 siblings.

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% with a clear description of the 'scope' parameter including examples. The tool description adds the context 'currently loaded' but does not further enrich parameter semantics 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 'List knowledge packs currently loaded in the persistent memory store,' with a specific verb and resource. It is distinct from siblings like load_knowledge_pack or unload_pack, but does not explicitly differentiate.

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?

No guidance on when to use this tool versus alternatives such as memory_list_facts or list_categories. The description provides no context for selecting this tool over others.

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?

Adds that custom registered platforms are included, which is a behavioral detail beyond the bare function. But without annotations, more details like auth requirements or rate limits 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?

Single sentence, efficient, front-loaded with the purpose. 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?

For a simple list tool with one parameter and no output schema, the description is fairly complete. It covers what and scope. Missing return format but acceptable.

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. Description adds no extra meaning beyond what the schema already provides for the category parameter.

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?

Description clearly states it lists platforms for a category, including custom ones. Verb 'list' and resource 'platforms' are specific. However, it does not explicitly differentiate from sibling list_categories, but context makes it clear.

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?

No guidance on when to use this tool vs alternatives like register_platform or list_categories. Lacks usage context 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?

No annotations are provided, so the description alone must convey behavioral traits. It notes 'recent' (though undefined) and 'from the local tracer,' but does not disclose ordering, pagination behavior, or whether the operation is read-only. The suggestion to use get_trace for full records adds some context.

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 primary purpose and then usage guidance. Every sentence adds value without redundancy or fluff.

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 list tool with two optional parameters and no output schema, the description covers the main purpose and links to a more detailed sibling. It could be improved by clarifying what 'recent' means, but overall it's adequately complete given the tool's 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 description does not add any meaning beyond the input schema. Schema coverage is 50% (only 'day' has a description). The parameter 'limit' lacks a description in both schema and tool description, leaving its purpose and constraints unexplained.

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?

Description clearly states 'List recent optimization traces' (specific verb+resource) and distinguishes from sibling 'get_trace' by noting 'Summary only; use get_trace for full records.' This explicitly differentiates the tool's purpose.

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?

Description provides clear guidance to use 'get_trace' for full records, indicating when to use this tool vs. an alternative. However, it does not specify when not to use this tool (e.g., if more than recent data is needed) or other contextual triggers.

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 partially covers behavior: chunking, embedding, and retrieval usage during optimize_prompt. However, it omits details on overwriting existing packs, error handling, performance implications, or side effects like data persistence.

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 sentences, front-loading the main action and then explaining chunking and source options. No wasted words, though slightly more structured formatting could improve readability.

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?

Covers core functionality (loading, chunking, sources), but lacks details on overwrite behavior, size limits, or unload mechanism. Given no output schema and basic complexity, it is adequate but not thorough.

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. The description adds marginal value beyond schema: it explains auto-detection of source types and mentions the community pack registry, but mostly repeats schema descriptions.

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 loads a knowledge pack (markdown with YAML frontmatter) into persistent memory for semantic retrieval, specifying chunking by heading and embedding. It distinguishes from siblings like list_packs (listing) and unload_pack (unloading) by focusing on loading for retrieval.

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 usage when needing to load documents for semantic retrieval, lists source types and a community registry, but does not explicitly exclude alternatives (e.g., memory_remember for facts) or provide when-not-to-use 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 provided, the description fully discloses behavior: it's a soft-delete, marks invalidated_at, removes from future searches, and preserves history. This is comprehensive for a single-parameter 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 sentences, front-loaded with the action, no wasted words, and essential information is efficiently presented.

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 tool with one required parameter and no output schema, the description is complete. It explains behavior, prerequisite, and effect on future operations. No 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 description coverage is 100% and already explains the id's sources. The main description does not add new parameter semantics beyond what the schema provides, 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 uses a specific verb 'Invalidate' and resource 'fact by its id'. It clearly distinguishes from siblings like memory_remember and memory_search by describing the bi-temporal soft-delete behavior, and it sets the context for how to obtain the id.

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 explicitly instructs to use memory_list_facts first to find the id, providing a clear prerequisite. However, it does not mention when not to use this tool or any alternatives, though for a simple delete this is adequate.

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?

Discloses core behaviors: lists live/non-invalidated facts, sorted by recency, optional filters. With no annotations, description carries full burden; missing details like pagination behavior, empty result handling, or side effects.

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 efficient sentences: first states operation and sorting, second provides use cases. No redundant information, well front-loaded.

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?

Covers purpose, filtering, sorting, and use cases. Lacks description of return format (e.g., fields like fact_id, predicate, value) but no output schema exists; would benefit from a brief hint about output structure.

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 3. Description mentions filtering by scope and predicate but adds no new meaning beyond schema descriptions which already detail defaults and examples. Limit parameter is not explicitly mentioned in description.

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?

Clearly states verb 'List' and resource 'live facts in persistent memory', with optional filtering by scope and predicate. Distinguishes from sibling tools like memory_search and memory_forget by specifying 'non-invalidated' facts and sorting order.

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 explicit use cases: 'inspecting what the engine knows' and 'finding fact ids to forget'. Implicitly excludes mutation or search operations, but does not explicitly state when not to use or name alternatives.

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 provided, the description carries full burden. It reveals the tool returns a fact id and implies persistence, but does not disclose potential side effects (e.g., overwrite behavior), required permissions, error handling, or whether it can fail silently.

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-load the purpose and usage context, with no redundant phrases. Every sentence serves a distinct function: purpose, usage guidance, sibling differentiation, and return value note.

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 parameter set (5 params, 3 required) and absence of output schema, the description covers the basic lifecycle (add, return id, forget). However, it omits details like whether adding duplicate facts creates duplicates or updates, and doesn't discuss scope isolation or session behavior beyond the schema.

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 the schema already explains all parameters. The description adds minimal meaning beyond the schema (only linking to `save_outcome` and `memory_forget`). Baseline 3 is appropriate as the description does not materially enhance parameter understanding.

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 'Explicitly add a fact to persistent memory' with a specific verb ('add') and resource ('fact'). It distinguishes from the sibling tool `save_outcome` by contrasting explicit vs implicit extraction, and notes the return of a new fact id for use with `memory_forget`.

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 explicitly states when to use: 'when the user says something the engine should remember across sessions' and provides examples. It mentions the complementary role of `save_outcome` and tees up `memory_forget` for the returned id, but does not explicitly list non-usage cases or other alternatives.

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 provided, so description carries the full burden. It discloses the search mechanism (vector similarity) and return types, but does not indicate whether the operation is read-only or any side effects, leaving ambiguity about safety.

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 fluff, front-loaded with the core purpose and followed by use case examples. 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?

No output schema, but description explains what is returned. Could be improved by mentioning result structure or pagination, but overall covers need-to-know aspects for a search tool.

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?

Two of three parameters have schema descriptions (67% coverage). Description does not add extra meaning beyond schema; it restates the purpose of the tool overall without detailing parameter usage. 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 states 'Semantic search over the persistent memory store' with specific resource ('memory store') and action ('search'), and lists what is returned. It distinguishes from siblings like memory_list_facts which are likely non-semantic.

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 'Useful for inspecting what ClarifyPrompt would retrieve for a given prompt, and for debugging curator decisions,' clarifying the context. No explicit exclusions or alternative comparisons, but context is clear.

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 provided, the description carries full burden. It discloses auto-gathering of workspace signals, intent resolution, mode recommendation, and grounding. It mentions support for many platforms and optional parameters with sensible defaults. It does not mention side effects, auth, or rate limits, but the coverage is good. No contradiction with 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 a single paragraph of about 6 sentences, each adding meaningful information. It is front-loaded with the main purpose and logically flows through features. Slightly long but still efficient; 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?

Given 14 parameters and no output schema, the description covers the analysis pipeline, default behaviors, optional features, and even mentions response structure via include_bundle. It could explicitly state that the response is an optimized prompt string, but the inference is clear from 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 coverage is 100%, so baseline is 3. The description adds value by explaining how parameters interact (e.g., category auto-detected, mode chosen from intent, session_id for few-shot). This goes beyond the schema descriptions and helps the agent understand the tool's behavior.

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: 'Optimize a prompt for a specific AI platform.' It uses a specific verb (optimize) and resource (prompt) and distinguishes itself from siblings like compose_prompt or critique_prompt by emphasizing context-awareness, auto-analysis, and multi-platform support.

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 explains that category, platform, and mode are optional with intelligent defaults, and that the engine auto-gathers workspace signals. However, it does not explicitly state when to use this tool vs alternatives like ground_prompt or compose_prompt, nor does it provide exclusions. The context is clear but lacks explicit 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?

No annotations are provided, so the description must disclose behavioral traits. It only says 'register a new platform' without mentioning side effects (e.g., overwriting an existing ID), authentication needs, or any implications. This is insufficient for safe invocation.

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 a single sentence, which is concise. It covers the core purpose without extra words. However, given the tool's complexity, slightly more structure (e.g., listing key prerequisites) could improve clarity.

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 lacks important context such as return values (no output schema), error conditions, and post-registration effects. For a tool with 7 parameters and no annotations, this is insufficient to ensure correct usage.

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 does not mention any parameters or their roles. With a schema coverage of 57%, the description adds no value beyond what the schema provides. The three undocumented parameters (syntax_hints, instructions, instructions_file) are left entirely unexplained.

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 (register) and resource (new custom AI platform for prompt optimization). This distinguishes it from sibling tools like update_platform and unregister_platform, 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 no guidance on when to use this tool versus alternatives such as update_platform or unregister_platform. There is no context about prerequisites or suitable scenarios, leaving the agent uncertain about selection.

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, but the description fully discloses the behavior: feeding the session ring buffer, triggering reflection for fact extraction/invalidation, and the latency impact on local models. It covers all significant side effects.

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 concise yet comprehensive. It front-loads the core purpose, then efficiently explains the two feedback loops and the reflection latency. Every sentence serves a purpose.

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 covers all essential aspects: the tool's function, its integration into two loops, behavior on each verdict, and a performance caveat. No output schema exists, but the side effects are fully described.

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 already has 100% description coverage, but the tool description adds operational context (e.g., how 'diff' helps reflection, the effect of 'skip_reflection') that provides additional meaning 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 it records the verdict of an optimization output (accepted/edited/rejected) and explains its role in two feedback loops, distinguishing it from sibling tools that handle other aspects of the optimization process.

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 usage after obtaining an optimization output, but does not explicitly state when not to use it or list alternatives. It provides clear context for when it is appropriate.

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?

Without annotations, the description adds moderate behavioral context by noting that unloading removes both chunks and embeddings. However, it does not disclose other important traits like destructiveness, reversibility, or authorization requirements, which would be expected for a tool with no 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 a single, well-formed sentence that is concise and to the point. Every word adds value, with no extraneous information.

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 simplicity of the tool (1 parameter, no output schema), the description is mostly complete. It explains the primary action and scope (pack, chunks, embeddings). Minor gaps remain, such as failure scenarios or state changes, but for a straightforward removal operation, it is adequate.

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%, and the parameter description in the schema is clear ('Pack id (as returned by list_packs)'). The tool description adds no additional semantic information beyond the schema, resulting in a baseline score of 3.

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 action (remove) and the resource (a loaded knowledge pack, including its chunks and embeddings). It effectively distinguishes this tool from siblings like 'load_knowledge_pack' and 'list_packs' by specifying its unique purpose.

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 no explicit guidance on when to use this tool versus alternatives (e.g., memory_forget for individual facts). It does not specify prerequisites or contraindications, leaving the agent to infer usage context from the tool name and schema alone.

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 should fully disclose behavior. It mentions removal and clearing overrides but omits side effects, permission requirements, or consequences.

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 a single, efficient sentence, but it could add more detail without becoming overly verbose.

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 no annotations, no output schema, and 0% schema coverage, the description is insufficient. It lacks information on return values, error conditions, and post-removal effects.

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%, yet the description provides no explanation of the three parameters (id, category, remove_override_only) or their roles.

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 removes a custom platform or clears instruction overrides on a built-in platform, distinguishing its purpose from siblings like register_platform and update_platform.

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 (removing or clearing overrides) but lacks explicit guidance on when not to use or alternatives among the listed siblings.

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, and the description only says 'update' and 'add/override', indicating mutation but lacking details on side effects, authorization, or what happens to unspecified fields. Behavioral transparency is minimal.

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 a single, concise sentence covering both use cases without unnecessary words. It is well-structured for its length, though breaking it into two sentences could improve clarity.

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 8 parameters and no output schema, the description is insufficient. It omits key details like required fields, partial vs full update behavior, and the meaning of complex parameters (e.g., instructions_file vs instructions, syntax_hints vs syntax_hints_append).

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 description does not explain any of the 8 parameters (e.g., id, instructions, syntax_hints). The agent has no insight into how to correctly populate the fields.

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 (update/add/override) and resource (platform), and distinguishes between custom and built-in platforms. However, it does not explicitly differentiate from sibling tools like register_platform, leaving some ambiguity about when to use each.

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 two modes (update custom, add/override built-in) but provides no explicit guidance on when to use this tool versus alternatives like register_platform or unregister_platform.

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