agent4.io

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

No annotations are provided, so the description carries full burden. It richly discloses server-side execution, path constraints, zip walk behavior (including relative-path naming and collision avoidance), ignored file types, and whole-archive rejection on problematic entries. Context like "subdirectories are walked" and "the whole archive is rejected" goes far beyond a basic summary.

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 longer than average but every sentence adds critical operational detail, using bold for the most important caveats. It is front-loaded with the core purpose and then expands into necessary behavioral warnings. No filler or redundancy, though it could be tightened slightly without losing 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 tool's complexity (server-side path limitation, binary vs text handling, folder ingestion via zip, archive edge cases), the description covers all relevant invocation scenarios. The output schema exists, so not detailing return values is acceptable. The only minor gap is silent on the optional title parameter, but that does not affect overall completeness for primary use cases.

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 description does not explicitly define all three parameters. It compensates significantly for the 'path' parameter by explaining server-side path semantics, but does not mention the 'title' parameter's meaning or the exact role of kb_name beyond being inferable. It adds value but leaves optional parameter details undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: "Add a local file's content to a knowledge base (txt/md/html/pdf/docx)." It clearly distinguishes itself from the sibling add_knowledge_text by explicitly recommending that tool for text files, making its own scope (binary-heavy formats and zip ingestion) unmistakable.

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 guidance: text files should be read and passed to add_knowledge_text, binaries should be uploaded via console or curl, and folders should be zipped. It also states the tool cannot read local machine paths, which is critical for correct invocation. This is exactly the when-to-use vs alternatives guidance expected.

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 behavioral transparency burden. It discloses that chunking and embedding happen synchronously and that the return value is the real chunk count, which is valuable. However, it does not cover error conditions or prerequisites, leaving some 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 two sentences, directly front-loads the core action, and uses structured formatting (bold for 'text') to highlight important context. Every sentence serves a purpose with no 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 tool with an output schema, the description is fairly complete: it states the operation, synchronous behavior, return value, and alternative for files. It does not mention edge cases like missing knowledge bases or size limits, but these are less critical given the tool's simplicity and output schema existence.

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 has 0% description coverage, and the tool description provides almost no parameter-specific meaning. It implicitly suggests 'content' is text, but there is no explanation of 'kb_name' or 'title' beyond their names, so the description fails to compensate for the schema 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 clearly states the tool adds a text document to a knowledge base, with explicit mention of synchronous chunking and embedding. It also distinguishes itself from the sibling 'add_knowledge_file' by addressing local files separately, making its scope obvious.

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 usage guidance by naming the alternative 'add_knowledge_file' for local files, indicating when to use this tool for text content. It also implies the appropriate context (text vs. files) without ambiguity.

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 it does so richly. It discloses that prose gets declined, that unresolved roles come back in `roles.unresolved` with candidates for the user to choose, and that dropped columns are not visible in later query results and should be reported. This reveals otherwise hidden behaviors and consequences beyond the schema.

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?

While the description is long, it is well-structured with clear paragraphs, bolded terms, and a bullet list for roles. Every sentence earns its place, from the purpose statement to the actionable guidance about `dropped`. The front-loading is strong, and the length is justified by the tool's complexity.

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 purpose, usage criteria, exclusions, parameter semantics, and important behavioral outcomes. It references an output report containing `roles.unresolved` and `dropped`, and since an output schema exists, the description does not need to enumerate return values. This is a complete guide for a complex 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?

The description adds deep meaning to the `roles` parameter, explaining exact extraction, listing specific role values (identity, link, image, code), and detailing unresolved-role behavior. The `name` parameter is not explicitly described, but its meaning is reasonably implied by 'for a knowledge base.' Since schema coverage is 0%, this is a strong compensation, though a brief mention of `name` would cement a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Build (or rebuild) the structured index for a knowledge base.' It clearly distinguishes this from vector search by explaining what vector search cannot do (count, filter numerically, aggregate), and it frames the tool as the 'second leg beside vector search.' This is explicit and differentiates it from related siblings like search_knowledge_base and get_knowledge_index.

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: 'Only worth it when the documents share a machine-readable header' and also gives a when-not: 'Prose gets declined, and that is the right answer.' It contrasts with vector search and refers to the follow-up SQL query tool, providing clear alternatives and context. The `roles` section also guides when and how to use the parameter.

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 of behavioral disclosure. It discloses several non-obvious traits (new key, unpublished, doesn't claim default, no chain pointer), giving the agent valuable expectations. It does not mention permissions or source-side effects, but for a clone operation, these are less critical.

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 that packs essential information without fluff. Parenthetical details are dense but well-organized, making it easy to scan.

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 (one parameter, no annotations, output schema present), the description is largely complete. It explains the purpose and key behavioral constraints. It could mention the relation to the original storyline, but the phrase 'new draft' implies non-destructive behavior, which is sufficient for an 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 0%, so the description must compensate for the parameter storyline_id. It does not mention the parameter at all, leaving the agent to infer its meaning from the tool name and schema title. This is a gap, though the parameter is relatively self-explanatory.

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 a specific action ('Clone a storyline') and outcome ('a new draft'), with explicit distinguishing details: new key, unpublished, doesn't claim default, no chain pointer. This sets it apart from sibling tools like create_storyline, update_storyline, or export_storyline.

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 phrase 'for tweaking' provides clear context for when to use this tool: when you want a safe copy to modify without affecting the original. However, it does not explicitly mention alternatives or exclusions, such as using create_storyline for new storylines or update_storyline for existing ones.

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 present, so the description carries full responsibility. It discloses server-side partial merge, derived foreground colors with WCAG contrast, overrides, logo fallback behavior, and custom_css behavior. This is rich, honest behavioral disclosure beyond what schema could provide.

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?

Though lengthy, the description is well-structured with bullet points and bolded key terms. Every paragraph adds value, no filler. The opening sentence states the overall purpose, and each parameter bullet is focused and informative. The length is justified by the tool's complexity.

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 parameters, prerequisites, alternatives, edge cases, and behavioral nuances (e.g., logo aspect ratios, color derivation, custom_css variables). It also references external examples. With an output schema present, there is no need to describe return values. This is a complete and self-sufficient description.

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 fully. It explains each parameter's meaning, format, defaults, and behavioral effects: label, theme_color, highlight_color, logo_url, input_mode, launcher, theme, and custom_css. Even token is mentioned ('Get the token from list_shares first'). Only agent_name is not described in detail, but the overall compensation is outstanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Configure this share — its name and its appearance.' It clearly distinguishes itself from create_share by stating that renaming is this call and you never need to create a replacement. This is precise and differentiates from siblings.

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 when-to-use guidance: renaming should use this call instead of delete/recreate. It gives a prerequisite ('Get the token from list_shares first') and recommends preferring theme_color over custom_css. Also notes input_mode's voice backend requirement. This is clear context with alternatives and 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 carries full burden — and it delivers thoroughly. It discloses name lower-casing, auto-enabled tools (time/geo/weather, compute_chart) that get replaced when tools is passed, ask_forms default-on behavior, compute_chart's arithmetic responsibilities, alias normalization and collision reporting via alias_result, and knowledge base retrieval injection. This is exemplary behavioral disclosure.

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

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

The description is dense but well-organized with clear paragraph breaks for distinct semantic clusters (name/soul/task/tools, ask_forms/compute_chart, alias). Each sentence earns its place — no filler. It's lengthy, but given the 10-parameter surface with 0% schema coverage, the length is justified. Slightly front-loaded with the core 'create an agent' statement.

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 10-parameter create tool with zero annotations, zero schema coverage, no enums, and significant behavioral quirks, the description delivers complete coverage. It covers every parameter, warns about the tools default-replacement trap, explains return-adjacent metadata (alias_result), and clarifies the published/share mechanics. With an output schema present and this level of description, nothing material is left unexplained.

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 entirely — and it does comprehensively. Every parameter gets semantic depth: name (key not display, lower-cased), soul/task (persona vs duties), tools (whitelist with default-replacement caveat), knowledge_bases (auto-injection), ask_forms (default and when to disable), alias (public slug, URL segment, normalization). This far exceeds compensating for the 0% 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 'Create an agent' with a specific verb+resource. It provides extensive detail distinguishing this from the many sibling tools (e.g., list_agents, update_agent, get_agent) by explaining the full parameter space and behavioral nuances of creation specifically.

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 gives substantial contextual guidance — it tells the agent to check list_tools first, explains when ask_forms is the natural move ('when it needs two or three facts before it can answer'), and advises passing ask_forms=False for prose-only agents. It doesn't explicitly name alternative tools for edge cases, but the guidance is strong and contextual.

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 takes on full responsibility for behavioral disclosure. It explains how 'description' routes questions, how 'instructions' affects model usage without affecting recall, and how 'top_k' impacts retrieval quality with empirical examples. It even mentions side effects like 'material in the prompt suppresses tool calls, dose-dependently'.

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 well-structured with headings, bold text, and bullet points, making it scannable despites its length. It is front-loaded with the core action and most critical guidance (description), but the overall length is substantial and could be trimmed without losing essential information. It earns its place for the most part, but is not 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 the tool's complexity (5 params, no annotations, no schema descriptions), the description is thorough. It covers all significant parameters, provides usage context, and includes worked examples. An output schema exists, so not explaining return values is acceptable. The empirical tuning data for 'top_k' adds real-world context that fully equips an 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 0%, so the description must fully compensate. It does so by explaining each parameter in depth: 'description' with routing logic, 'instructions' with structure and examples, 'max_distance' with defaults and calibration advice, and 'top_k' with range, defaults, and evidence-based tuning. Even 'name' is implicitly covered by the creation context.

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 'Create a knowledge base', a specific verb + resource statement. It then elaborates on the tool's key configuration fields, making its function unmistakable and distinct from sibling tools like add_knowledge_file or update_knowledge_base.

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 extensive guidance on how to configure parameters (e.g., writing 'description' and 'instructions', setting 'top_k' based on document shape), but it does not explicitly discuss when to use this tool versus alternatives like add_knowledge_text or update_knowledge_base. Usage is implied rather than stated with 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 full burden and excels. It discloses return values (chat_url, qr_url, pretty_url), the behavior of token rotation, the distinction between machine/embed forms and human-friendly links, and provides integration code. It also explains what the share enables and the consequences of not setting aliases, offering transparency beyond a simple 'create' 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 long but well-structured with bolded key points and logical sections. Every sentence adds value, covering purpose, output, embedding, alternative channels, and best practices. It is not redundant, but the length exceeds typical descriptions, making it slightly less concise than ideal.

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 is exceptionally complete for a tool with an output schema. It explains the output fields in detail, provides real-world usage scenarios (no website, business cards, embed widget), and links to related setup steps. It covers all aspects an agent would need to use this tool correctly, even 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?

The schema has no parameter descriptions (0% coverage), but the description compensates by explaining the 'label' parameter with examples ('website widget', 'support link') and implies the role of 'agent_name' as the target agent. However, it doesn't explicitly define 'agent_name' beyond the schema, leaving a minor 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's purpose: 'Create a **share / integration entry point** for an agent — this is how end users actually reach it.' This is a specific verb+resource combination that distinguishes it from sibling tools like publish_storyline and configure_share, and it explains the core concept of 'published vs reachable.'

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 extensive guidance on when to use the tool and how to handle different scenarios. It explicitly says 'published=True only means visible, not reachable' and instructs to 'fix that proactively' when pretty_url is missing. It also directs users to alternative channels (Telegram/WhatsApp) and explains when to prefer pretty_url over the /s/ link, giving clear decision criteria.

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 of behavioral disclosure. It explicitly reveals that instructions are only visible after load_skill is called, warns about model fabrication of return values, and mentions the returned warnings field. This goes well beyond the basic create operation and discloses critical behavioral nuances.

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 'Create a skill' and then provides essential field guidance and paradigm explanation. While the paradigm paragraph is dense, every sentence adds information about critical pitfalls and system behavior. It is appropriately structured despite being longer than average.

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 the core operational paradigm, the roles of the main fields, and warns about common mistakes. However, it omits any explanation of the 'tools' parameter, which is a significant gap given the absence of annotations and parameter descriptions in the schema. Since an output schema exists, not detailing return values is 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?

The description clearly explains the meaning of the 'description' and 'instructions' parameters, but does not address the 'tools' parameter, which is not self-evident. Since schema description coverage is 0%, the description only partially compensates for the missing parameter information, leaving a notable 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 'Create a skill' with a specific verb and resource. It further elaborates on the two key fields (description and instructions), making the tool's purpose unambiguous and distinct from sibling create tools like create_agent or create_knowledge_base.

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 substantial context on how to use the tool effectively: what to put in description vs instructions, the importance of triggers in the description, and avoiding promises of return values. While it doesn't explicitly contrast with update_skill or other alternatives, the guidance is clear and directly applicable to the tool's usage.

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 compensates. It discloses nuanced behaviors: concurrency semantics (progress belongs to user vs session), user_visibility levels and their UI implications, how parallel nodes manage completion, enrollment behavior (is_default, allow_agent_enroll) and the critical note that without enroll_trigger the agent 'almost never enrols'. It also explains that control flow composes deterministically and that case state vs profile dimensions are handled differently.

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 lengthy but well-structured with line breaks, code formatting, and distinct sections for graph, Node, Exit, RuleAst, enrollment, etc. Every sentence carries technical value. It is not a terse summary, but the density is justified for a tool with 18 parameters. A slight deduction for verbosity; it could be split into bullet points or headers, but the inline code and grouping make it navigable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is remarkably complete. It covers graph schema, node types, exit kinds, rule AST, control flow patterns (if/else, loops, AND-joins), enrollment behavior, and even provides a documentation link. It includes all major parameter explanations and accounts for the output schema by not needing to describe return values. It leaves little ambiguity for an agent to invoke 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%, so the description carries the full burden. It provides deep meaning for many parameters: user_visibility and learner_visibility with legacy mapping, concurrency with examples of use cases, graph structure with full Node and Exit schemas, profile_schema, on_complete/next_storyline_id relationship, is_default, allow_agent_enroll, and enroll_trigger. This goes far beyond the bare 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 opens with a clear, specific action: 'Create a storyline draft.' It also differentiates from sibling tools by prescribing the next steps: 'After creating, self-check with validate_storyline, then publish_storyline.' This makes the tool's role distinct from validation and publishing, and it clearly targets creation of a new storyline.

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 states the workflow after creation (validate and publish), which implies this tool is for the initial draft. It also gives detailed guidance on when enrollment parameters matter (e.g., 'in that case ALWAYS write enroll_trigger'). However, it does not explicitly contrast with update_storyline or clone_storyline, so it lacks a direct exclusion for 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 exist, so the description must bear the burden of behavioral disclosure. It does state the tool is a read operation returning a list and notes the empty-input edge case, but it does not mention side effects, error conditions, or the role of the context parameter. This is moderate disclosure but not comprehensive.

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 appropriately concise: the first sentence states the core purpose, and the second paragraph adds parameter explanations and workflow. It is front-loaded, uses bold for emphasis, and every sentence contributes value without redundancy.

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 the main workflow and two of three parameters, but it omits the context parameter and does not enumerate valid field values, relying on a reference to improve_prompt. Given no annotations and no output schema, these gaps make the description adequate but not fully complete for correct invocation in all cases.

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 0% schema description coverage, the description compensates by explaining the field parameter (same values as improve_prompt) and the current parameter (the text to diagnose, required, empty not useful). However, the context parameter is completely omitted, and field values are only given by reference rather than enumerated, so it is not fully self-contained.

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 that the tool reads a field and returns a string array of specific improvement suggestions. It distinguishes itself from improve_prompt by positioning it as a diagnostic precursor, and the verb 'read' plus the explicit output type make 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 explicitly provides a typical flow: use diagnose_prompt first, pick suggestions, then fold them into improve_prompt's hint. This references the sibling tool improve_prompt and establishes when to use this tool. It also gives a precondition (non-empty current text), offering clear usage 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 burden of behavioral disclosure. It discloses the output format and the fact that tenant/version/id are excluded, implying a portable export. However, it doesn't explicitly state that the operation is read-only or has no side effects on the original storyline.

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 that front-loads the action, includes specific output details, and states use cases without excess 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 the simple one-parameter operation and an existing output schema, the description is largely complete, covering the tool's purpose, use cases, and output characteristics. It could add an explicit read-only note, but overall it is sufficient.

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 provides no description for storyline_id (0% coverage), and the description does not explain the parameter beyond the obvious name. It fails to compensate for the schema's lack of description, leaving the agent to infer that storyline_id is the unique identifier.

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 exports a portable storyline JSON, specifying the format (schema_version + definition) and exclusions (tenant/version/id). This distinguishes it from sibling tools like import_storyline and clone_storyline.

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 names use cases: backup, migration, or re-import. This gives clear context for when to use it, though it doesn't explicitly mention alternatives or when not to use it.

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 burden. 'Get' implies a read operation, and 'full configuration' indicates the scope of the return. However, it doesn't disclose behaviors like error handling for missing agents or any access 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?

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and the content of the configuration. 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 getter with one parameter and an output schema, the description is largely complete. It clearly states what is returned. It doesn't address edge cases like non-existent agents, but that is not critical given the output schema exists.

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% for the single parameter 'name'. The description does not explain what 'name' refers to (agent name vs. ID), adding no value beyond the schema's field name and type.

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 gets one agent's full configuration and lists the specific components (soul/task/tools/skills/knowledge_bases/model/params). This distinguishes it from sibling tools like get_skill or get_knowledge_base and from list_agents.

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 when you need a single agent's complete configuration, contrasting with list_agents for listing. However, it doesn't explicitly name alternatives or state when not to use this tool.

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. It clearly states what is included (profile fields, spaces, console_url) and what is never included ('Never any conversation content'), which is a strong privacy guarantee. It stops short of addressing error handling or access control, but this is sufficient for a simple get 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, front-loaded with the main action, and every sentence adds value: the first identifies the resource and fields, the second adds exclusions and a return value detail. 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 one-parameter get tool, the description covers the scope of data returned, privacy constraints, and a notable output field (console_url). The output schema exists to handle return values, so the description is adequately complete for an agent to select and invoke 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?

The schema provides no description for the single required parameter 'uid', and the description doesn't explicitly define it beyond the context of getting 'end user's detail'. Since 'uid' is a self-explanatory acronym, the description partially compensates, but it doesn't specify format, source, or how to obtain it.

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 'Get one end user's detail' which is a specific verb+resource pair, and enumerates the exact fields returned (name, contact email/phone, city, timezone) plus their spaces. This distinguishes it from sibling list_end_users, which retrieves multiple users, and from other get_* 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 phrase 'one end user' implies this is for a single user detail, contrasting with list_end_users for multiple users. However, it does not explicitly mention alternatives or exclusions, so it's clear but not as directive as naming the alternate tool.

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 of disclosing behavior. 'Get' implies a read-only operation, but it does not explicitly state this or mention potential error conditions, authentication requirements, or rate limits. It does add a useful detail about the full instructions text being included, which suggests a possibly large response, but overall transparency is moderate.

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 that is front-loaded with the action and resource, and every word adds value. No filler or redundant content.

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 tool is simple (one parameter) and has an output schema, so return values are documented. The description covers the core purpose and a notable detail (full instructions text). However, it lacks explicit read-only disclosure or failure scenarios, but given the tool's simplicity, it is largely complete.

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 has one parameter 'name' with no description (0% schema coverage). The description says 'Get one knowledge base's configuration,' implying that 'name' identifies which knowledge base to retrieve, but it does not explicitly define the parameter's format, uniqueness, or required nature beyond the schema's required flag. This adds some meaning but leaves room for ambiguity.

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 ('Get') and the resource ('one knowledge base's configuration'), and adds a distinguishing detail ('including the full instructions text shown to the model') that separates it from listing or searching knowledge bases. This is a specific and unambiguous 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 implies when to use this tool: when you need the full configuration, including the instructions text, for a single knowledge base. This context differentiates it from list_knowledge_bases, which likely returns summaries. No explicit exclusions are stated, but the phrasing provides clear usage context.

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 responsibility. It goes beyond a simple read operation by explaining that zeros are missing values that 'silently poison every average, minimum and range filter,' includes a real-world example, and instructs the agent on how to report findings. This is strong behavioral 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?

Front-loaded with a clear summary, then a bolded emphasis and a detailed anecdote. The anecdote is compelling but adds length; still, each sentence earns its place by reinforcing the tool's value and usage guidance.

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 purpose, behavioral nuances, and reporting expectations. With an output schema present, it doesn't need to describe return values. The main gap is parameter semantics, but overall this is a well-rounded description.

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 has zero description coverage for the single 'name' parameter, and the description never clarifies that 'name' refers to the knowledge index being inspected. While the parameter is named intuitively, the description provides no additional meaning, leaving the agent to infer what name is expected.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Show the structured index profile' and lists concrete components (coverage, type, numeric range, top values, warnings). This clearly distinguishes it from sibling tools like build_knowledge_index and patch_knowledge_index, which modify rather than read the index.

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 frames the warnings as the tool's central purpose and notes 'Nothing else in the platform will ever tell them,' implying this is the go-to tool for surfacing data-quality issues. However, it does not explicitly name alternatives or state when not to use it, so it's clear but not fully explicit.

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. It discloses the return scope (full content including instructions), which adds useful context. However, it does not mention side effects (likely none), permissions, or error behavior. For a read-only getter, the description is adequate but 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?

One sentence, 13 words, concise and front-loaded. Every word serves a purpose, with no redundant 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 output schema exists, return values need no description. The tool is simple with one parameter, and the description covers the main purpose and the notable detail about including instructions. It lacks error-handling details, but for a simple retrieval tool it is sufficiently complete.

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 parameter (name), and the schema provides only type/title with no description. The tool description does not mention the parameter or how it is used. With 0% schema coverage, the description must compensate, but it fails to explain that the skill is identified by its name or any naming conventions.

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 identifies retrieval of a single skill's full content, distinguishing it from list_skills (which would list all skills) and other skill operations. It specifies the verb (get), resource (skill), and the scope (full content including instructions).

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 usage context is clear: use when you need the complete content of a specific skill. It does not explicitly mention alternatives, but the distinction from list_skills is implied. A more explicit note about using list_skills for browsing would improve it, but it is not necessary for this simple getter.

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 the return scope (whole graph, profile_schema, top-level fields) which is useful, but does not mention any side effects, error behavior, permissions, or rate limits. For a read operation, this is a moderate gap.

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 that front-loads the core purpose and specifies return content. It contains 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 the simple one-parameter schema and the presence of an output schema, the description covers the return content but lacks usage guidance and parameter semantics. The lack of annotations and explicit alternative tool references leave notable gaps for an agent choosing and invoking this 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?

The schema has one parameter (storyline_id) with 0% description coverage. The tool description does not explain the parameter format or semantics beyond what the name implies. It does not compensate for the low schema coverage.

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 that this tool retrieves a single storyline's full definition, specifying the included components (whole graph, profile_schema, top-level fields). It uses the specific verb 'Get' and names the resource, distinguishing it from siblings like list_storylines or export_storyline.

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 is provided about when to use this tool versus alternatives. The description implies using it when you need a full definition, but does not mention exclusion criteria or alternatives such as list_storylines or export_storyline for different use cases.

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 and exceeds it. It discloses version-aware rejection, always-creates-new semantics, key collision auto-rename behavior, and the effect of override_agent_name. These are behavioral traits beyond the schema.

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, front-loaded with purpose, and each sentence provides distinct value: purpose, the artifact category, payload definition, and behavioral rules. No fluff or redundancy.

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 complexity (versioning, collisions, overrides), the description covers the key behavioral aspects. It does not explain the output/return (but an output schema exists) nor explicit prerequisites beyond the agent existence, leaving a small gap in 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?

Schema coverage is 0%, but the description compensates: it defines payload as the structure from export_storyline (schema_version, graph, profile_schema, top-level fields) and explains override_agent_name rebinding with the agent existence condition. Both parameters are semantically explained.

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 imports an exported storyline JSON as a draft, with a specific verb and resource. It distinguishes itself from sibling tools by noting that generated storylines from novel/source material land here, and the import/export relationship is evident.

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 provides a clear use case ('Artifacts like... land here') and mentions the payload comes from export_storyline, implying when to use it. However, it does not explicitly name alternatives or state when NOT to use it, so it lacks an 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?

With no annotations, the description fully carries behavioral disclosure. It explicitly states the return format: 'Returns only the improved text, no explanation, no wrapper,' and mentions that the caller places it next to the original for human approval. It also describes edge behavior (empty current = draft from scratch). This is transparent and actionable.

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 moderately sized but every sentence earns its place. The line-separated list of field values is structured and readable, though slightly dense. It avoids fluff and stays focused on essential operational details.

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 4 parameters, no annotations, and an output schema present, the description covers all necessary aspects: purpose, parameter roles, expected output, and usage context. It 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 0%, but the description compensates thoroughly. It explains 'field' with the full enumerated list and semantics, describes 'current' as existing text, 'hint' as direction, and 'context' as on-site context with a note on specificity. This adds meaning far beyond the bare 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 function: 'Rewrite a field's text to work better as an AI system prompt; returns the improved text.' It specifies the resource (a field's text) and distinguishes from siblings like diagnose_prompt by focusing on rewriting rather than analyzing.

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 guidance on when to use: for improving any of the listed field types. It explains the meaning of each field category and advises providing context for better results. It also clarifies optional parameters (hint, current, context) and what they do, giving clear direction for effective use.

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 burden. The term 'list' implies a read-only operation, and the description adds scoping ('in this tenant') and output details ('name + published state'). It does not explicitly state side effects or permissions, but for a simple list operation, this is adequate.

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 that states the action, scope, and output fields. No wasted words; it is front-loaded and easily parsed.

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 list tool with an output schema, the description fully covers what the tool does and what it returns. The output schema handles return structure details, and the description provides the necessary 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?

The tool has zero parameters and 100% schema coverage (empty object). The description adds no parameter info, but with no parameters, the baseline of 4 is appropriate since there is nothing to clarify.

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 'list' with a clear resource 'agents' and scope 'in this tenant', and further specifies output as 'name + published state'. This clearly distinguishes it from siblings like get_agent (single agent) and create_agent.

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 context is clear: this tool lists all agents in the tenant. It implicitly contrasts with get_agent (which fetches a single agent), but there is no explicit 'when not to use' or named alternative.

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 and does well: it discloses the roster-only nature, returned user fields, sorting semantics, and pagination ritual (passing next_cursor back). It does not mention rate limits or the exact ordering of 'recent' (ascending vs. descending), but these are minor for a read-only list 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 well-structured and dense: purpose at the top, followed by response highlights, filter/sort semantics, pagination, and a typical call. Every sentence earns its place with no 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?

Given that the output schema exists and the tool is a straightforward list operation, the description covers all essential aspects: result contents, filter/sort options, pagination, and a practical usage example. It provides enough information for an agent to select and invoke the tool correctly without needing to consult additional sources.

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 no parameter descriptions (0% coverage), so the description must add meaning—and it does: 'q filters by name or external id', 'sort ∈ recent | tokens24h', and pagination via cursor. The 'limit' parameter is left to inference, but its default (50) is visible in the schema and its meaning is self-evident.

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 this tenant's end users' and explicitly scopes it as 'roster only, never any conversation content,' distinguishing it from session-related sibling tools. It names the resource (end users) and the action (list), 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 a concrete typical use case—'list_end_users(sort="tokens24h") to find the most active / most expensive users'—which helps an agent decide when to use it. However, it does not explicitly name alternative tools (e.g., list_user_sessions) or state when not to use it, stopping short of full when/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 no annotations, the description carries the full transparency burden. It discloses that the output includes doc/chunk counts and relevance cutoff, which is valuable behavioral context beyond a simple list. It also scopes to the tenant, but doesn't state read-only or auth requirements, though it's implied. This is adequate for a simple 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 a single, focused sentence that starts with the verb 'List,' immediately conveying the action and resource. It includes necessary details without any redundant 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 the tool has no parameters and an output schema is provided, the description sufficiently covers the tool's purpose and output content. 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 zero parameters, and schema coverage is 100% (empty properties). The baseline for 0 params is 4. The description does not need to add parameter info, and it doesn't conflict with 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 lists 'this tenant's knowledge bases,' a specific verb-resource pair with scope, distinguishing it from singular get_knowledge_base. The mention of doc/chunk counts and relevance cutoff further specifies the output. This matches a high purpose clarity.

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 context by saying 'List this tenant's knowledge bases,' making clear it is for enumerating all KBs for the tenant. However, it does not explicitly mention alternatives like get_knowledge_base or state exclusions. This is clear context without exclusions, scoring a 4.

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 explicitly states the operation is read-only and that secret fields are omitted, which are key behavioral traits. This goes beyond a minimal statement and covers main safety and data-privacy concerns.

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, front-loaded with the tool's purpose, followed by a useful security note. Every word earns its place with no redundant 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 tool has zero parameters, an output schema, and a simple listing function, the description covers all necessary aspects: what it lists, the scope (tenant's tool library), and the read-only/secret omission note. No additional context is needed.

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 zero parameters, and the schema is complete. The description does not need to add parameter-specific details; the baseline for no-parameter tools is 4, and the description satisfies this without requiring compensation.

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 ('List') and resource ('MCP servers') with a clear scope ('in this tenant's tool library'), making its purpose immediately identifiable. It also distinguishes itself from sibling list tools that target other entity types (e.g., list_agents, list_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 for when the tool would be used (to list MCP servers), but it does not explicitly mention alternatives or exclusion criteria. Usage is implied by the tool's name and description, but no direct comparison with sibling tools is offered.

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 full burden. It discloses the returned attributes (match rules, greeting mode, position), but doesn't mention behavior like pagination, performance implications, or data limitations. For a simple list operation, this is adequate but not rich.

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. It conveys the action, scope, and included fields without any wasted words. Perfectly 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?

With zero parameters and an output schema present, the description is fully sufficient for a list operation. It states breadth ('all') and scope ('of this tenant'), which are the only context needed. No gaps apparent.

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 are zero parameters, so the schema is complete and the description doesn't need to explain parameter syntax. Baseline 4 applies; the description adds no unnecessary param info, which 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 ('List') and resource ('page playbooks'), clearly indicating it retrieves all such entities for the tenant. The parenthetical adds key attributes (match rules, greeting mode, position). It doesn't explicitly distinguish from siblings like page_context_stats or resolve_page_context, but 'all page playbooks' clearly implies a list-all operation.

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 purpose implies usage: when you want to list all page playbooks. However, there are no explicit 'use this instead of X' exclusions or alternative recommendations. Siblings like resolve_page_context and upsert_page_context are contextually related, but no guidance is provided on when to choose this tool over them.

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 transparency burden. It explicitly discloses the returned fields and the nuance that 'pretty_url' is the preferred link for humans. The verb 'list' implies a read-only operation, and no hidden side effects are suggested, though it does not explicitly state auth requirements or pagination behavior.

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 with no filler. It front-loads the core action and field list, then adds a concise, valuable note about pretty_url. 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?

The tool is simple with one required parameter and an output schema, so the description need not explain return values in detail. It covers the essential behavior, output fields, and a key nuance about the preferred link. It is complete enough for an agent to invoke and interpret results, though it lacks explicit notes about empty results or error conditions.

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 no descriptions (0% coverage), so the description must compensate. It does connect the single parameter 'agent_name' to 'an agent's shares', giving some meaning. However, it does not clarify whether the value is the agent's name vs. ID, case sensitivity, or relationship to agent_name used in other tools beyond a cross-reference to create_share.

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: 'List an agent's shares' with a specific verb, resource, and scope. It also enumerates the content of the listing (token, label, disabled, chat link, embed URL, appearance config), and this distinguishes it from sibling tools like create_share and configure_share.

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 this tool: it is the listing operation, as opposed to create/configure variants. It also gives practical guidance about the 'pretty_url' field and cross-references 'see create_share', but it does not explicitly state when not to use it or name alternative 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, so the description must carry the burden. The verb 'List' implies a read-only operation with no side effects, and 'this tenant's skills' narrows scope. However, it does not mention pagination, ordering, or error behavior, though the output schema covers return 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 entire description is one short, direct sentence with no wasted words. It is perfectly front-loaded and 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 the tool's simplicity—zero parameters and an existing output schema—the description fully covers the operation. No additional context is required.

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 zero parameters, and the schema reflects that. The description correctly adds no parameter information, as there is nothing to explain. 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 clearly states the action 'List' and the resource 'this tenant's skills', which is specific and distinguishes it from sibling tools like get_skill or create_skill. The scope is clarified with 'this tenant's'.

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 the use case by naming the resource and action, but provides no explicit guidance on when to use it versus alternatives such as get_skill or list_knowledge_bases. No exclusions or alternative references are given.

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 tenant scoping, optional filter, and included fields, but does not mention ordering, pagination, or whether soft-deleted items are included. For a list operation, some behavioral 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?

The description is a single, front-loaded sentence with no filler. It efficiently conveys purpose, scope, and optional filter.

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 (1 param, output schema exists), the description covers the essentials. Minor gaps like pagination/ordering are not critical for a list tool but would slightly enhance 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?

The single parameter 'agent' is explained by the phrase 'optionally filtered by agent', adding meaning to the schema. Since schema description coverage is 0%, the description compensates well for the one param.

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 storylines for the current tenant, optionally filtered by agent, and includes specific fields (state, version, default flag). This distinguishes it from sibling list tools (e.g., list_agents, list_skills) and the singular get_storyline.

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 you need to list storylines) but provides no explicit guidance on when to prefer this over get_storyline or when to use the optional agent filter. No alternatives or exclusions 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?

No annotations are provided, so the description carries the transparency burden. 'List' implies a read-only operation, and the description adds scope (assignable to agents, MCP tools). However, it does not explicitly state safety or side-effect-free behavior, though the verb 'list' strongly conveys this.

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, tightly worded sentence. It front-loads the action ('List') and resource ('tool names assignable to agents') and adds relevant context about including MCP tools.

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 listing tool with an output schema, the description is complete. It states what is listed and the scope, and the output schema covers return values. No further explanation is needed.

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 zero parameters, so the schema covers everything. The description adds no parameter details, but with no params, the baseline is 4, as nothing more is needed.

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: listing tool names assignable to agents, along with their descriptions. It specifies the scope (including tenant's connected MCP tools) and distinguishes from siblings like list_mcp_servers or list_agents.

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 on when to use: when you need to see tools that can be assigned to agents, including MCP tools. It does not explicitly exclude alternatives, but the context is specific enough to guide 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?

With no annotations, the description carries full burden. It discloses that message bodies are not returned, that console_url deep-links and auto-opens, that pagination requires passing next_cursor as cursor, and that links should be given to the tenant. This is exceptional transparency for a read-only list 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 moderately long but every sentence contributes: scope, metadata fields, console link behavior, and pagination. It is front-loaded with the core purpose and uses bold formatting for emphasis. No filler or redundant clauses.

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 (3 params, no nested objects) and presence of an output schema, the description covers all essential aspects: what it returns, what it doesn't return, how to access transcripts, and how to paginate. It is complete enough for an agent to select and invoke 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 provides no parameter descriptions (0% coverage), so the description must compensate. It explains cursor semantics via 'pass next_cursor back as cursor' and implies uid identifies the end user. Limit is not explicitly described but is self-evident with a default. It adds meaningful context beyond the raw 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 opens with 'List one end user's sessions' — a specific verb, resource, and scope. It explicitly notes metadata-only and distinguishes from sibling tools like list_end_users by targeting sessions for a single user. The purpose is 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?

It provides clear usage context: how to obtain the console_url and hand it to the tenant for human reading. It also describes pagination usage. However, it does not explicitly state alternatives or when not to use this tool, so it stops short of a perfect score.

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 behavioral disclosure burden. It discloses the core metrics returned and implies a read-only operation, but it does not mention permissions, data scoping, or operational constraints beyond 'per playbook'.

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, well-structured sentence front-loads the key metrics and ends with a memorable purpose clause. Every word earns its place; 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?

With an output schema present and zero parameters, the description provides sufficient context for a simple stats tool. It clearly states the per-playbook scope and analytical intent, though it could slightly benefit from clarifying whether results are global or filtered.

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 zero parameters, so the schema already covers all parameter semantics completely. The description adds useful context about what the metrics mean but needs no parameter-level explanation.

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 provides open counts and suggested-question click counts per playbook, with an explicit use-case ('find copy nobody clicks'). This is a specific, distinctive resource and metric set that separates it from sibling tools like usage_stats.

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 phrase 'find copy nobody clicks' gives a clear analytical context for when to use this tool. It does not name alternative tools or exclusions, but it gives enough guidance to infer intended use over general stats 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?

With no annotations provided, the description carries the full burden of disclosure. It reveals critical constraints (only emits add/modify/remove/refused), explains refusal behavior for unsupported data, and specifies that applying is cheap (no re-embedding). These details go well beyond what annotations would typically provide.

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 efficiently structured in three tight paragraphs: definition and examples, refusal behavior, and usage workflow. Every sentence adds value, and the bolded caveat emphasizes a key point without redundancy.

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 the presence of an output schema (which covers return values), the description adequately covers purpose, usage, and behavioral caveats. It explains the apply workflow, refusal handling, and cost implications, making it self-sufficient for an 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 0%. The description partially explains `request` via examples and `apply` via 'call with apply=false first', but the required `name` parameter is never explicitly defined. An agent must infer that it refers to the knowledge index to patch, which is a significant gap for a required field.

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 with a specific verb ('Change') and resource ('structured index schema'), and provides concrete examples that distinguish it from sibling tools like build_knowledge_index. The scope is explicit: modify the schema incrementally via plain-language requests.

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 gives clear operational guidance: call with apply=false first, show the user what would change, batch edits, and apply once. It also explains that applying marks the index for rebuild without re-embedding, which is useful context. It does not explicitly name alternative tools or say when not to use, but the usage pattern is well 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 carries the full burden. It discloses the no-persistence side effect, the return shape ({plan, backend, warnings}), and even explains the subtle 'agent's own deliverable' stall risk in warnings. This is exceptionally transparent and goes well beyond the bare minimum.

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 most critical fact (no persistence), followed by practical usage guidance, then the return/warnings details. Every sentence adds value, and the structure is clean and scannable.

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, the presence of an output schema, and the absence of annotations, the description is complete enough. It covers purpose, usage, side effects, return structure, and a subtle behavioral trap, leaving little ambiguity for an 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?

The schema has 0% description coverage, so the description must compensate. It clarifies that `goal` is the planning objective and that `agent` has a `task` constraining the steps, but it does not specify expected formats (e.g., whether `agent` is an ID or name) or elaborate on `goal` semantics in detail. Partial compensation, not complete.

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 verb and resource: 'Generate a plan for a goal and return it for review.' It also distinguishes itself from persistence-related siblings by emphasizing 'without persisting anything' and explicitly listing what it does not do (no temporary storyline, no enrollment, no user affected).

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 use cases: 'inspect plan quality before trusting the feature in production' and 'see how the agent's task constrains the steps.' It does not name alternative tools or state when not to use it, so it falls short of a full 5, but the 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, the description carries the full burden. It discloses key behaviors: validation with HTTP 422 on blocking errors, freezing an immutable version, and marking the story published. This is strong transparency, though it omits permission requirements or reversibility nuances.

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 'Publish a storyline', followed by a concise workflow. Every word adds value with no redundancy.

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 (one parameter) and the presence of an output schema, the description covers the essential workflow and side effects. It might mention preconditions or whether republishing is allowed, but these are minor 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?

The schema has only one parameter, storyline_id, but the description provides no explanation of it. Schema coverage is 0%, and the description does not compensate by describing the parameter's meaning or usage.

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 ('Publish') and resource ('a storyline'), and details the workflow (validates, freezes immutable version, marks published). This clearly distinguishes it from sibling tools like validate_storyline and unpublish_storyline.

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 indicates the tool performs validation and publishing in one action, giving clear context for when to use it. However, it does not explicitly mention alternatives or when not to use it, so it falls short of the highest 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?

No annotations are provided, so the description bears the responsibility. It uses 'show' to imply a read-only operation and adds valuable context about silent production failures, which is beyond what structured data would convey. Yet it does not explicitly rule out side effects or discuss permissions, leaving minor 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 only two sentences, with the primary purpose front-loaded and the second sentence adding relevant motivation. Every word earns its place, with no fluff or repetition.

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 output schema exists, so return details are covered. The description provides essential context about match-rule pitfalls and the production impact, making the tool's value clear. However, the lack of parameter explanation prevents full 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?

The input schema has two params (key, url) with no descriptions and 0% coverage, so the description must compensate. It only says 'URL (or key)' without explaining what a key is, how the two params interact, or required formats. This leaves significant ambiguity for the agent.

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: given a URL or key, show which playbook it resolves to. The verb 'show' and the resource 'playbook' are specific, and the tool is distinguished from siblings like list_page_contexts and upsert_page_context by its resolution focus.

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 advises to 'always verify after writing a match rule', giving a clear when-to-use context. It also explains the danger of glob-matching pitfalls, emphasizing the tool's role in verification. However, it does not mention alternatives or when not to use it, 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'top passages with title, layer, url and a snippet' and that content is public with no tenant data. This provides good behavioral insight, though it could mention if results are ranked or any API-specific behavior.

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 long, front-loading the main action and purpose. Every sentence adds value: what it searches, when to use, and what it returns. 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 the tool's simplicity and the existence of an output schema, the description adequately covers purpose, usage, and return fields. The only shortfall is the lack of parameter explanations, which reduces completeness slightly.

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, but it does not explain any parameter details. The 'query' parameter is implied but not described as a search string, and 'k' (default 5) is not mentioned at all. The user must infer their meaning from context.

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 searches 'agent4.io's own product docs' and distinguishes between 'concepts' and 'cookbook recipes'. This specifies the resource and scope, differentiating it from siblings like 'search_knowledge_base' which searches user knowledge bases.

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 advises using the tool when unsure about a feature, term, or how to build something. It mentions the content is public and involves no tenant data, providing clear context. However, it does not explicitly state when not to use it or compare directly with alternatives like 'search_knowledge_base'.

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 burden. It discloses that the tool uses exactly the same retrieval path as real conversations, adding context that results are aligned with actual agent behavior. It also clarifies empty result semantics, which is valuable behavioral information beyond the schema.

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 crisp sentences, front-loaded with the core action, followed by an important nuance. No filler or redundant 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 tool's simplicity, the description covers the essential usage and behavioral caveats. An output schema exists to define the return structure, so the description need not elaborate. It lacks explicit alternatives, but overall the context is sufficient.

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 has no descriptions (0% coverage), so the description should compensate. It implies that 'query' is the user question and 'kb_name' is the target knowledge base, but does not specify formats or whether kb_name is an ID or name. This adds minimal meaning beyond the schema, so a 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 tool's action ('Search this knowledge base') and result ('returns matching chunks with distances'), and distinguishes its purpose by noting it uses the same retrieval path as real conversations, positioning it for validation rather than general search.

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 guidance to use it to validate cutoff and chunking, and explains the meaning of an empty result. However, it does not mention when to use alternative search tools like search_agent4_docs, so it lacks exclusions or 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 fully discloses behavioral traits: async verification with immediate check and re-checks every 10 minutes, status lifecycle (pending vs active), certificate issuance on first visit, one-domain-per-tenant constraint, and that changing agent_alias does not re-run verification. It also explains error semantics (403 = upgrade needed) and Cloudflare failure modes. This far exceeds the minimum disclosure burden.

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?

Although long, the description is efficiently structured with bold key points and bullet-like paragraphs. Every sentence provides actionable information: prerequisites, DNS specifics, verification mechanics, constraints, and error conditions. It is appropriately sized for the tool's complexity and front-loads the core purpose before diving into nuances.

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 high complexity (DNS setup, async verification, edge cases) and minimal schema annotations, the description covers all critical aspects: prerequisites, verification flow, status meanings, Cloudflare caveat, one-domain rule, agent_alias behavior, and plan limitation. It also mentions response fields (cname_target, status, last_error) providing context without needing to detail return 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?

The input schema has 0% description coverage (no parameter descriptions), so the tool description must compensate fully. It does: 'domain' is explained as a subdomain-only restriction with examples, and 'agent_alias' is thoroughly described with empty vs set behavior (landing on tenant page vs specific agent chat). The description adds rich semantic meaning beyond raw schema names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource combination: 'Bind the client's own domain to this tenant's chat pages'. It clearly distinguishes this tool from siblings by focusing on custom domain binding, an action not covered by other tools like set_pwa_branding or tenant_info. The purpose is unambiguous and detailed.

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 when-to-use and prerequisites: DNS CNAME must be configured first, subdomains only, special Cloudflare DNS-only requirement, plan restriction (403), and async verification behavior. It even explains when not to call or what alternative actions trigger verification (calling again re-triggers). This is exemplary usage 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 fully carries the behavioral burden and goes deep: it explains server-side derivation of favicon/icons/maskable sizes, centre-cropping of non-square images, platform-specific install prompt behavior (Android system dialog vs iOS Share guide), and the return value (final config). These traits are not inferable from annotations or schema.

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 opens with a concise summary, then uses a bulleted list for parameter semantics, and wraps up with a clear statement about optionality and return. Every sentence adds value and there is no wasted space; the structure makes complex platform details scannable.

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 that the tool has 3 parameters, an output schema, and no annotations, the description covers all essential aspects: purpose, parameter meaning, behavioral variations (platform differences), and return value. It even points to a Cookbook walkthrough for further detail, making the description self-sufficient for correct 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 schema provides only titles and defaults with zero descriptions (0% coverage), so the description completely compensates. It defines each parameter in detail: `agent` (required target), `icon_source_url` (format, minimum size, squareness, cropping, derived sizes), and `install_prompt` (all three options with behavioral implications).

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 ('Configure a specific agent's PWA branding and install experience') and clearly distinguishes it from siblings by explaining the per-agent standalone chat page scope. It also names the exact resource (agent branding) and the unique effect (each agent is its own app), making the purpose unmistakable.

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 strong context for when to use this tool (when configuring an agent's PWA branding/install experience) and notes that icon/prompt parameters are optional and independent. However, it does not explicitly exclude alternatives or name when not to use it, though no sibling tool competes with this function.

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 of behavioral disclosure. It specifies the content returned (basic info, quota, custom-domain status), but does not explicitly state it is a read-only operation or mention any potential side effects, errors, or prerequisites.

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 that directly states the tool's scope. No unnecessary words, and the optional clause about custom-domain binding is efficiently included.

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 (no parameters) and the presence of an output schema that likely details return fields, the description provides sufficient context. However, it does not specify which tenant is being referenced (e.g., current tenant), leaving slight ambiguity.

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 zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it adds some context about the returned data, which is relevant to the tool's purpose.

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 indicates the tool returns tenant basic info and quota, including optional custom-domain binding status. It is specific and distinct from sibling tools, though it lacks an explicit verb like 'get' or 'retrieve'.

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. There is no mention of use cases, exclusions, or related tools, leaving the agent to infer its application.

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 and does an excellent job: it discloses that nothing is stored, no session/enrollment is created, tokens count toward quota, and that the judge is probabilistic. It also states the tool only reads the judge and does not affect user acceptance.

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 a clear purpose statement, then organizes parameter explanations in a compact paragraph, and ends with return values and scope. Every sentence contributes essential information without redundancy.

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?

Despite having an output schema, the description still enumerates the return fields and explains the business-domain gate concept. It gives enough context for the agent to understand when and how the judge works, including probabilistic behavior and the separate acceptance step.

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%, but the description thoroughly explains messages (last is current, rest are earlier), samples (re-runs for stability), and expect (pass true/false to get matched). Agent is the only parameter not directly explained, but it is obvious from context and the schema title.

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 a specific verb and resource: 'Dry-run the Dynamic Planner's escalation judge' and asks a concrete question. It clearly distinguishes this tool from similar ones like test_skill_trigger by focusing on the planner and the escalation judge.

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 tells when to use the tool: 'Use it after editing the agent's task' and explains why. It also clarifies what the tool does NOT do—does not determine if the user accepts the offer—which provides an important exclusion boundary.

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 responsibility for behavioral disclosure. It clearly states that 'tool side effects are NOT executed', 'no session is stored', tokens count toward quota, and there are hard limits (messages≤5, samples≤5, at most 25 calls). It also explains what is captured (tool-call decision) and highlights the 'claimed_without_call' failure mode. This is exceptionally transparent.

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?

Though long, the description is well-structured and front-loaded with the core purpose. Each sentence adds value: purpose/safety, modes, limits, return fields, and a concrete workflow. No filler or redundancy is present, and the bullet-like format aids scanability. Given the tool's complexity, this level of detail is justified and earns a high score.

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 tool is complex with 6 parameters, two modes, side-effect safety, and return analytics. The description covers all key aspects: what it does, when to use it, how parameters map to behaviors, limits, expected outputs (hit counts, claimed_without_call), and even edge-case testing advice. An output schema exists, so omitting detailed return structure is acceptable. This is a complete, self-contained description.

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 explains 'loaded' in detail, gives limits for 'messages' and 'samples', and implies 'skill' and 'agent' through workflow context. However, the 'expect_tool' parameter is never mentioned or explained, and 'agent' is only indirectly referenced via 'tenant's actual model routing.' Given 6 parameters, this is partial but not complete coverage, so the minimum viable 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 opens with 'Reality-check whether your prompts actually trigger tool calls (dry-run)', using a specific verb and resource that clearly distinguishes this from siblings like diagnose_prompt or improve_prompt. It explicitly frames the tool as a dry-run test rather than a production action, making its purpose unmistakable.

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 gives explicit when-to-use guidance: 'run this after writing/changing a skill' and contrasts with 'instead of counting corpses in production.' It details two modes (loaded=false vs loaded=true) with specific use cases, and even outlines a full workflow loop (create_skill → check warnings → test_skill_trigger → adjust → retest). This is exemplary usage 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 carries full burden. It discloses critical behavioral traits: no more auto-enrolment, in-flight users degrade silently, progress is kept, and re-publishing resumes it. This is rich behavioral transparency covering reversibility and user impact.

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?

One dense, information-packed sentence with no filler. Every element—auto-enrolment, in-flight user degradation, progress retention, re-publishing—earns its place. Efficiently structured with a parenthetical for archive.

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 simple tool (1 parameter) and the presence of an output schema, the description covers all essential aspects: the action, side effects, data safety, and reversibility. It is complete for its scope without needing to explain return values.

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 storyline_id is straightforward and its meaning is implied by the tool name, but schema description coverage is 0%. The description does not explicitly define storyline_id or its format, so while the parameter is obvious, the description does not compensate for the missing schema detail.

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 action: 'Unpublish (archive)' with specific consequences ('no more auto-enrolment', 'in-flight users silently degrade to the plain agent'). This distinguishes it from the sibling tool publish_storyline and other storyline operations.

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 scenarios (e.g., when you need to stop auto-enrolment) but does not explicitly contrast with alternatives like publish_storyline or provide exclusions. It lacks direct 'use this instead of X' guidance, so it is adequate but not explicit.

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. It discloses that list fields (tools, skills, knowledge_bases) are full-list replacements, that skill-bound tools don't appear in the agent's own tools list, and that auto_suggest incurs an extra LLM call per turn. It also warns against assuming success equals 'enabled,' which is a valuable non-obvious behavioral trait.

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 long but every section earns its place: list-field warning, verification guidance, skill-bound tools note, and auto_suggest behavior. It is front-loaded with the most critical partial-update semantics and uses formatting (bold, warning emoji) to draw attention. For a 21-parameter tool, this length is justified, though a slightly tightened version could be easier to scan.

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 tool has 21 parameters, no annotations, and no schema-level descriptions. The description covers the most error-prone areas (list-field replacement vs incremental, verification, skill-bound tools, auto_suggest cost). An output schema exists for return values, so the description need not explain those. Missing details on a few boolean fields are minor since their names imply their purpose.

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 has 0% description coverage, so the description must compensate. It thoroughly explains the nuanced semantics of tools/skills/knowledge_bases (full-list) versus add_/remove_ variants (incremental), and describes auto_suggest and suggest_prompt in detail. However, it does not cover every parameter (e.g., soul, task, model, published), though those are relatively self-explanatory from their names and types.

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 'Update **part** of an agent — fields you don't pass stay as they are,' which clearly identifies the action (partial update) and resource (agent). This distinguishes it from siblings like create_agent, get_agent, and list_agents, and the partial-update semantics prevent confusion with full replacement.

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 when to use alternatives: 'To "add one / remove one", use add_tools / remove_tools (and add_/remove_skills, add_/remove_knowledge_bases): incremental, idempotent, leaves the rest untouched.' It also advises reading the response after the call to verify the final list, giving concrete post-usage 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 carries the full burden of behavioral disclosure. It transparently reveals that the update is a server-side PATCH merge, meaning unspecified fields are preserved, which is a critical behavioral trait not evident from the schema alone. It does not cover error cases (e.g., non-existent knowledge base) or side effects, but the core mutation behavior is clearly described.

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 that directly states the action and adds the key merge behavior. Every word earns its place, and the dash and parenthetical clarify the PATCH semantics without unnecessary detail.

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 tool has a moderate complexity with 5 parameters, but the description focuses only on the update semantics. Since an output schema exists, return values are covered. However, it lacks guidance on parameter constraints (e.g., valid ranges for top_k or max_distance) and does not explicitly mention that the knowledge base must already exist, which is important for an update operation. Overall, it is adequate but leaves room for more 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?

The schema has 0% description coverage for its parameters, so the description must compensate. However, it only says that not-passed fields stay unchanged, without explaining the meaning of individual parameters (e.g., top_k, max_distance, instructions). While 'name' and 'description' are self-explanatory, 'top_k' and 'max_distance' lack context, leaving a significant gap in 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 the operation ('Update') on a specific resource ('knowledge base') and clarifies that it performs a partial update via server-side PATCH merge. This distinguishes it from related tools like create_knowledge_base (creation) and get_knowledge_base (retrieval). The verb-resource pairing 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 implies the tool is used for modifying an existing knowledge base, and the PATCH merge note clarifies that omitted fields retain their values. However, it does not explicitly state when to use this tool versus alternatives (e.g., create_knowledge_base for new resources, or update_agent for agents), nor does it mention any prerequisites or exclusions. The usage context is implied rather than stated.

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 responsibility for behavioral disclosure. It clearly discloses PATCH merge behavior ('fields you don't pass stay as they are'), the full-list replacement nature of tools, the incremental/idempotent nature of add_tools/remove_tools, and the automatic propagation to agents. This is comprehensive.

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 dense: one sentence for core PATCH behavior, one focused warning block for tools replacement. It is front-loaded with the primary purpose and contains 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?

With an output schema present, return values are covered. The description fully addresses the key operational nuances (merge semantics, tool replacement, incremental add/remove, and automatic agent effect) making it complete for a tool of this complexity. Missing aspects like error handling are not necessary for the description to be complete.

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 crucial semantics for tools-related parameters (tools full-list, add_tools/remove_tools incremental). However, it does not elaborate on description or instructions parameters beyond their obvious names, leaving those to schema field names only.

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 'Update part of a skill' which is a specific verb+resource, and further clarifies the semantics with 'server-side PATCH merge, no GET+PUT round-trip.' This distinguishes it from a full update tool and from the sibling create_skill, making the purpose unmistakable.

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 provides explicit within-tool guidance: 'tools=[...] is full-list replacement; to add/remove one use add_tools/remove_tools' and explains that bound tools automatically affect agents. However, it does not explicitly contrast with create_skill or other sibling update tools, relying on the name for that distinction.

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 excels. It discloses the GET-then-merge PUT mechanism, concurrency semantics, future-enrollment-only impact, a historical bug affecting graph replacement, explicit clearing instructions, optimistic locking via expected_version, and a post-update verification/validation step. This is exemplary transparency for a mutating 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 multi-paragraph but every sentence earns its place. It front-loads the core partial-update concept, then systematically covers concurrency, the graph pitfall, validation, and locking. The formatting with bold and the warning emoji improves scannability without 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?

Given the tool's high complexity (20 params, partial semantics, concurrency, optimistic locking, destructive potential), the description covers all critical aspects: what partial means, how concurrency affects future runs, how to clear the graph safely, how to handle version conflicts, and what to do after updating. It also leverages create_storyline as a reference and mentions validate_storyline for verification.

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 has 20 parameters with 0% description coverage, but the description adds critical semantics for concurrency (enumerating 'user' vs 'session' behavior), graph (partial semantics and how to clear), and expected_version (optimistic locking). It also points to create_storyline for complex structures. Most other parameters are self-explanatory from names, but not all are individually explained, so 4 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 opens with 'Update **part** of a storyline draft' which clearly identifies the verb ('update'), resource ('storyline draft'), and the crucial partial-update scope. It distinguishes itself from siblings like create_storyline by emphasizing that unspecified fields are preserved, making the tool's unique role 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 gives excellent context on when to use this tool: for partial updates where omitted fields are retained. It also provides explicit guidance for clearing the graph (pass empty arrays) and points to create_storyline for structure details. However, it does not explicitly contrast with create_storyline or clone_storyline, so it falls short of a perfect 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 provided, the description carries full behavioral burden and excels. It discloses full-replace defaults, url_pattern path-only matching with query/trailing-slash behavior, resolution order, and greeting_mode generation behavior.

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 dense but well-organized, front-loaded with the core purpose, and uses backticks for parameters. Every sentence adds critical value—no fluff, with clear separations for context, url_pattern, and full-replace warnings.

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 9-parameter tool, the description covers the complex behaviors fully (full-replace, resolution order, glob syntax, greeting modes). Minor gaps remain for label/position/is_default semantics, but an output schema exists to handle return values.

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 has zero descriptive coverage, so the description compensates for key, context, url_pattern, greeting_mode, greeting, and questions. However, label, position, and is_default are not explained, leaving those parameters underspecified.

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 'Create or fully replace a page playbook,' which clearly states the action and resource. It distinguishes this upsert from partial updates and references sibling list_page_contexts for the merge workflow.

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 instructs when to use the tool vs alternatives: 'To change one field, list_page_contexts first, merge, then send.' Also provides when-not guidance ('do NOT write facts like prices') and explains url_pattern matching behavior and greeting_mode 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?

With no annotations, the description carries the behavioral burden. It discloses that only metadata is returned and never conversation content, a key privacy trait. It also enumerates the valid group values beyond the schema. It doesn't explicitly state read-only, but the term 'statistics' strongly implies it.

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: one for purpose, one for parameter domain, one for data nature, and one for examples. Every sentence adds value without redundancy, and the structure is front-loaded with 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?

For a single-parameter stats tool with an output schema, the description covers purpose, parameter semantics, data scope, and usage guidance. It does not need to describe return values since the output schema exists. The description is complete enough for an agent to select and invoke 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?

The schema provides a bare string parameter with a default but no enum or description. The description fills this gap entirely by listing all valid group values and giving semantic examples ('who uses the most', 'busiest agent'), which are essential for correct invocation.

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 provides usage statistics, enumerates grouping dimensions (total, agent, user, space, day, model), and specifies that it returns token/event counts, distinguishing it from content-access tools. The usage examples imply a query action, making the purpose explicit.

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 guidance on parameter selection ('Use group="user" to see who uses the most, group="agent" for the busiest agent'), which helps the agent choose the right grouping. However, it does not explicitly compare with sibling tools like page_context_stats, so there are no exclusion statements.

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 the validation scope, the return shape ({ok, errors}), and the publish-gating behavior, which is solid, but it doesn't explicitly state whether the operation is read-only or if it has side effects beyond validation.

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 primary action, and every clause adds value ('Must pass before publishing' is highly actionable). No filler or redundancy.

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 one-parameter tool with an output schema, the description covers the core scope and return format, and ties it to publishing. It could mention prerequisites like 'storyline must exist' but the essential context 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?

Schema description coverage is 0% and the description does not elaborate on the storyline_id parameter beyond its name. The agent gets no additional semantic guidance about the parameter, leaving the schema and name to carry all 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 clearly identifies the tool as validating a storyline graph, enumerating specific validation dimensions (entry, dead ends, unreachable, dangling, cross-line targets, rule dimensions). This distinguishes it from sibling tools like publish_storyline or update_storyline.

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 statement 'Must pass before publishing' provides clear context that this is a prerequisite to publishing, but it does not explicitly mention when not to use it or name alternative validation tools.

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