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

Adds valuable performance context beyond annotations ('shares a single catalog parse') explaining the efficiency mechanism. States batch limit constraint. Does not contradict readOnly/idempotent annotations.

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

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

Three sentences, each high-value: purpose statement, efficiency rationale with sibling comparison, and operational constraint. No filler text.

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?

Strong coverage for a read-only batch tool with complete schema annotations. Minor gap: no output schema exists, and description does not clarify return structure (e.g., results grouping), though this is somewhat implied by 'batch_query' naming.

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 has 100% description coverage, so baseline applies. Description mentions 'Max 10 queries' reinforcing the constraint but does not add semantic meaning to individual query parameters (q, domain, etc.) beyond what's in 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?

Specific verb 'Search' + resource 'topics' clearly stated. Explicitly distinguishes from sibling 'query_knowledge' by contrasting single-call vs multiple calls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('More efficient than calling query_knowledge multiple times') and names the alternative tool. Includes operational constraint ('Max 10 queries per batch') guiding usage limits.

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

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

Annotations declare readOnlyHint and idempotentHint. The description adds valuable behavioral context about the return value format ('full raw markdown with YAML frontmatter, inline source citations...') that annotations do not cover. Does not mention error cases or rate limits, preventing a 5.

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

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

Two sentences with zero waste: first states purpose, second details return format. Front-loaded with the core action. Every word earns its place.

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

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

For a simple single-parameter retrieval tool, the description is complete. It compensates for the missing output schema by detailing the return format (markdown structure, content types). Combined with complete annotations and full schema coverage, no gaps remain.

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 100% schema description coverage for the single 'unit_id' parameter, the schema carries the semantic burden. The description mentions 'by ID' but does not add syntax details or usage examples beyond what the schema already provides, meeting the baseline for high-coverage schemas.

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

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

States specific verb ('Retrieve') + resource ('knowledge unit') + exact scope ('by ID'). The 'specific...by ID' phrasing clearly distinguishes it from sibling tools like 'query_knowledge' (search) and 'batch_query' (bulk 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?

Implies usage context through 'specific knowledge unit by ID,' signaling this is for exact lookups rather than searches. However, it does not explicitly name sibling alternatives (e.g., 'use query_knowledge for searches') or state 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds useful workflow context (discovery phase before querying) and hints at return content (unit counts), but omits details about pagination, caching, or response format that would help the agent handle the output.

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

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

Two sentences with zero waste. The first front-loads the action and resource; the second provides usage context. Every word earns its place with no redundancy or tautology.

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, read-only annotations) and lack of output schema, the description adequately covers the essential information: what it returns (domains with unit counts) and why to use it (discovery). It appropriately compensates for missing output schema by describing the payload content.

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

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

With zero parameters, the baseline score per rules is 4. The schema is empty (100% coverage of nothing), and the description appropriately focuses on behavior rather than inventing parameter documentation where none exists.

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 provides a specific verb ('List'), clear resource ('knowledge domains'), and scope detail ('with unit counts'). It effectively distinguishes this discovery tool from siblings like query_knowledge and batch_query by emphasizing the enumeration of available topics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence ('Use this to discover what topics are covered before querying') provides clear context for when to invoke the tool relative to sibling query tools. However, it could be strengthened by explicitly naming the query siblings (query_knowledge, batch_query) rather than using the generic term 'querying'.

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

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

Annotations declare read-only/idempotent/open-world properties, so description focuses on adding return structure details ('ranked by relevance', 'confidence scores, source counts, token estimates') and workflow sequence. Does not contradict annotations.

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

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

Three tightly constructed sentences with zero waste: workflow position and action, return format specification, and error-handling guidance. Front-loaded with the critical 'STEP 1' designation.

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 lacking an output schema, the description compensates by detailing the return metadata structure. Combined with 100% input schema coverage and complete annotations, this provides sufficient context for a search tool, though it could explicitly highlight the filtering capabilities (domain, region, jurisdiction) present in the schema.

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

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

Schema description coverage is 100%, providing complete documentation for all 6 parameters (query, domain, region, jurisdiction, entity_type, limit). Description implies the query parameter through the search verb but adds no syntax details beyond the schema, warranting the baseline score of 3.

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

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

Specific verb ('Search') + resource ('knowledgelib.io knowledge units') combination clearly defines the scope. Explicitly distinguishes from sibling 'suggest_question' by stating when to use that alternative instead.

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 workflow positioning ('STEP 1') and clear fallback instruction ('If no results are found, use suggest_question'). Names the specific alternative tool to invoke in failure 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?

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds valuable lifecycle context ('Reports are reviewed and used to prioritize content updates'), but does not elaborate on side effects, persistence behavior, or what the caller should expect after submission (e.g., confirmation of receipt).

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

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

Three sentences with zero waste: purpose (sentence 1), usage triggers (sentence 2), and post-submission behavior (sentence 3). Information is front-loaded and every clause 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?

Given the 5 parameters with full schema coverage and no output schema, the description adequately covers the tool's purpose, invocation triggers, and downstream workflow. It could be improved by noting whether the operation is synchronous or if it returns a report ID, but it is sufficient for agent selection.

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 100% schema description coverage, the schema carries the heavy lifting for parameter semantics. The description maps general concepts ('incorrect, outdated, or broken') to the tool's domain but does not add syntax details, validation rules, or usage examples beyond what the schema already provides, warranting the baseline score.

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 ('Flag') and clear resource ('content on a knowledge unit'), explicitly stating the tool's function. It effectively distinguishes this tool from retrieval-oriented siblings like get_unit or query_knowledge by focusing on error reporting rather than data access.

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 positive guidance ('Use this when you notice factual errors, dead links...') that clearly scopes when to invoke the tool. However, it lacks explicit negative guidance or named alternatives (e.g., 'Do not use for general questions; use query_knowledge instead'), which would earn a 5.

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

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

Annotations declare idempotentHint=true and non-destructive write behavior. The description adds valuable business logic: 'Popular suggestions are prioritized for new knowledge unit creation' and 'The next agent that asks the same question will get an answer', explaining the long-term effect. Does not contradict annotations (submit/write aligns with readOnlyHint=false).

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 'STEP 3' workflow indicator. Four sentences each earning their place: (1) action definition, (2) trigger conditions, (3) business logic/prioritization, (4) future effect. No redundant or wasted language.

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 3-parameter submission tool without output schema, the description adequately covers workflow position, triggering conditions, and downstream effects (future agent availability). Minor gap: does not describe the immediate return value (e.g., confirmation ID or success status).

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

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

Schema description coverage is 100% with clear examples for each parameter (question, context, domain). The description mentions 'question or topic request' aligning with the question parameter, but does not add semantic guidance beyond what the fully-documented schema already provides, warranting the baseline score.

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

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

Description uses specific verb 'Submit' with resource 'question or topic request' to target 'knowledgelib.io'. It clearly distinguishes from sibling 'query_knowledge' by positioning this as the fallback when querying returns no results, clarifying its role in the knowledge acquisition 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 states 'ALWAYS call this when query_knowledge returned no results' and 'when a user asks about a topic that should be covered', providing clear when-to-use conditions and implicitly referencing the alternative tool (query_knowledge) for the primary path.

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