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 explains the tool reads the YAML knowledge base and returns a formatted string or error, but lacks details on side effects, rate limits, or security implications.

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, with a clear header and structured args/returns section. Every sentence adds value, though the args section could be more compact.

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 presence of an output schema, the description adequately explains the return value (formatted schema string or error). It covers the tool's purpose and input, though additional behavioral details could improve 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_id' is described with origin ('from list_agents()'), adding context beyond the schema's type and title. Schema coverage is 0%, so the description compensates well.

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 returns the schema for an agent (tables, columns, types, foreign keys). The verb 'return' and specific resource differentiate it from siblings like list_agents or query.

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 using the tool before formulating a question to inspect available tables/columns. It provides context but does not explicitly state when not to use or name alternatives.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states the tool returns a formatted stats string, implying a read-only operation. However, it does not detail error behavior (e.g., missing agent_id), permissions, or side effects. The mention of Qdrant collection adds some context but leaves 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 concise with two sentences and a structured Args/Returns list. Every sentence adds value with 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?

Given the tool's simplicity (one parameter, straightforward return), the description covers the essential information. It mentions what stats are reported and the return format. The presence of an output schema reduces the need for extensive return details. Minor omission: no mention of what happens if the agent has no cache.

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

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

Schema coverage is 0%, so the description must compensate. It explains 'agent_id: Agent to inspect', which clearly defines the parameter's purpose. For a single, simple string parameter, this is sufficient and adds value beyond the schema.

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

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

The description begins with a specific verb-resource pair ('Return cache statistics for an agent'), clearly stating the tool's function. It further specifies the exact data reported (number of cached entries, Qdrant collection name). This distinguishes it from sibling tools like get_agent_schema or invalidate_cache.

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 for inspecting an agent's cache stats but provides no explicit guidance on when to use it versus alternatives or when not to use it (e.g., if cache is empty). No prerequisites 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 provided, so the description carries the full burden. It mentions returning a 'formatted history string, newest first' but does not disclose whether the tool is read-only, has side effects, requires specific permissions, or handles errors. This is minimal behavioral insight.

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 (about 60 words) and well-structured with 'Args' and 'Returns' sections. Every sentence adds value; 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?

Given the tool's simplicity and presence of an output schema, the description explains the return format and ordering. It could mention behavior on empty results or errors, but overall it's fairly complete for a retrieval 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?

Schema coverage is 0% (no descriptions in schema), so the description must add meaning. It defines 'agent_id' as 'Agent to look up' and 'limit' with default and maximum values. This adds significant value beyond the bare schema 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 clearly states the tool returns 'recent queries and their feedback ratings for an agent'. It specifies the resource (query history) and the action (return). The sibling tools like 'submit_feedback' and 'query' are distinct, so no confusion.

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 basic arguments and returns but does not explicitly state when to use this tool versus alternatives. It implies usage for a specific agent but lacks exclusionary guidance or context on 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?

With no annotations, the description fully discloses behavior: runs four checks in sequence, each described (LLM, Qdrant, Embed daemon, Config), and states it returns a formatted status report string. No contradictions.

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?

Description is concise: one-line summary, numbered list of checks, and return value. Front-loaded and well-structured with 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 tool with no parameters and an output schema, the description covers purpose, behavior (all checks), and output format completely. No gaps.

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

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

No parameters exist, so baseline is 4. The description adds no parameter info as none 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?

Description clearly states it checks connectivity to all NLQueries dependencies, listing four specific checks. It uses a specific verb 'check' and resource, and distinguishes from sibling tools which serve different purposes (e.g., query, cache management).

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

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

Description implicitly tells when to use the tool (to verify connectivity) and provides clear context through the listed checks. However, it does not explicitly state when not to use it or compare to alternatives, though the unique health-check function makes this clear.

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

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

With no annotations provided, the description carries full burden. It states the effect ('Drop the entire semantic cache') and that the cache is rebuilt automatically. It also mentions the return type (confirmation string). It does not cover permission requirements or irreversibility, but is sufficient given the tool's simplicity.

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 (5 short sentences including structured Args/Returns) and front-loads the main action. The Args/Returns section is slightly redundant but acceptable.

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 nested objects, no output schema), the description covers all necessary aspects: action, usage context, behavior, parameter meaning, and return type. It is complete for an agent to correctly invoke the 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?

Schema description coverage is 0% for agent_id, but the description adds 'Agent whose cache should be cleared.' This fully explains the parameter's purpose, compensating for the lack of schema description.

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

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

The description clearly states the tool's purpose: 'Drop the entire semantic cache for an agent.' It uses a specific verb and resource, and distinguishes itself from sibling tools like get_cache_stats and get_query_history which are read-only.

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 says when to use: 'Use this after a schema change or data refresh to force fresh SQL generation.' It implies when not to use (only when invalidation is needed), but does not mention alternatives. However, no alternative tool exists for invalidation.

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

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

No annotations provided, so description carries full burden. It discloses return format (sorted list of strings), example, empty list case, and underlying mechanism (YAML files, KB_PATH). This fully informs the agent of 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?

Description is concise, using two short paragraphs. First sentence front-loads the main purpose. Each subsequent sentence adds necessary detail 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 no parameters and presence of output schema (confirmed by context signals), description covers return type, example, edge case (empty list), and contextual background about agent availability. It is fully 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?

No parameters exist (0 required). Schema coverage is 100% (empty properties). Baseline score of 4 applies since description needs no additional param info.

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

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

Description clearly states the tool returns IDs of all available agents, with a specific verb 'Return' and resource 'IDs of all agents'. It distinguishes from siblings like 'get_agent_schema' and 'list_connectors' by focusing on agent listing.

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

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

Description explains when agents are available (YAML file exists in KB_PATH) and how to create one ('nlqueries export-kb'). It provides clear context for usage but does not explicitly mention when not to use this tool or compare to alternatives.

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

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

Discloses important behavioral trait: passwords and full URLs are redacted for safety. Also mentions return format. No annotations exist, so description carries the burden adequately.

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?

Very concise, front-loaded with main action. Returns section adds value without redundancy. 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?

Given zero parameters and an output schema, the description provides sufficient context about purpose, behavior, and return format. No gaps for simple listing 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?

No parameters in schema, so baseline is 4. Description adds no parameter info (unnecessary). Schema coverage is 100%.

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

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

Clearly states it lists registered database connectors and their types, with specific verb 'List' and resource 'connectors'. Differentiates from siblings like list_agents or get_query_history.

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 for seeing registered connectors, but lacks explicit when-to-use, when-not-to-use, or alternatives. Sibling differentiation is implicit via distinct names.

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

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

No annotations provided, so description carries full burden. Discloses that the tool translates question to SQL or searches documents, and returns a formatted answer with SQL, citations, and metadata. Does not mention side effects, but likely read-only.

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?

Well-structured with purpose statement, detailed explanation, Args section, and Returns section. Front-loaded and every sentence adds value.

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?

Complete for a query tool with 3 parameters. Describes return format, mentions sibling tool list_agents for discovery, and covers all necessary behavioral aspects.

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?

Despite 0% schema description coverage, the description explains all three parameters in detail: question (natural-language question), agent_id (with reference to list_agents), and dialect (default and supported values). Adds significant meaning beyond 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?

Description clearly states the tool asks a natural-language question to an NLQueries agent. It specifies the verb 'ask' and the resource, and distinguishes from sibling tools like list_agents or health.

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 for using the tool: translate question to SQL or search documents. Suggests using list_agents() to discover agent_ids. Lacks explicit when-not-to-use or alternatives, but context is strong.

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 covers file storage location, usage for accuracy improvement, and return value. It could mention side effects like overwriting or permissions, but overall good.

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 bullet points, front-loaded with purpose. Every sentence adds value, though slightly lengthy. Could be more concise without losing clarity.

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

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

Given no output schema details, the description explains return type and ties the tool into a larger workflow. Could mention error handling or when corrected_sql is required, but adequate overall.

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 provides clear meanings for each parameter, including valid values for rating and optionality of corrected_sql, adding significant value beyond the schema.

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

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

The description clearly states the verb 'Record' and the resource 'user feedback for a query result'. It distinguishes from siblings by focusing on feedback, while siblings handle queries, cache, etc.

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

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

The description implies when to use (after a query result) and explains the feedback's purpose. It lacks explicit exclusions or comparisons to alternatives, but the context makes it clear.

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