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

With no annotations, the description carries the burden and does well: it discloses the underlying source (the agent's YAML knowledge base), that output is compactly formatted, that partial column lists are annotated as such, and that a not-found agent yields an error message. It omits only secondary traits like auth requirements or rate limits, which is a minor gap for a read-only lookup.

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 the core purpose in sentence one, followed by operational context and a compact Args/Returns block. The Returns section partly restates what the output schema already encodes, which is mild redundancy, but nothing is padded.

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 read tool with an output schema present, the description covers everything an agent needs: what is fetched, why, the partial-column caveat, and the failure mode. Return-value detail is already in the output schema, so no essential information is missing.

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 and largely does: 'agent_id: Agent ID from list_agents()' tells the agent both the meaning and the upstream call that supplies the value. It does not specify the ID format or an example value, leaving a small residual 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?

States a specific verb and resource ('Return the schema for an agent') and enumerates exactly what is returned: tables, columns, types, foreign keys. This cleanly separates it from siblings like list_agents (enumeration) and query (execution), so an agent can pick it without opening the schema.

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?

Gives a clear situational cue: inspect available tables and columns 'before formulating a question,' which positions it as a pre-step to query. It stops short of naming exclusions or an explicit alternative (e.g., when to skip it because list_agents already suffices), so it falls just 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 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 carries the full burden and does so well: it discloses that the tool is reachable without credentials, that probe_llm defaults to false, that enabling it spends a real token and returns latency plus a key check, and that the other three checks are non-destructive endpoint probes. This is exactly the cost/auth/default context an agent needs before invoking.

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 the one-line purpose, then a scannable bulleted list of checks, then Args/Returns — a good structure. It is slightly padded by the editorial aside about billing someone for asking whether their server is up, which costs a sentence without adding call-relevant 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?

An output schema exists so return formatting needn't be explained, and the description still states it returns a formatted status report string. Every dependency checked, the cost tradeoff, the default, and the credential-free access are all covered — nothing an agent needs to call this correctly is missing.

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 single parameter's schema entry is only a title and default, so the description must compensate — and it does, explaining precisely what probe_llm does on and off (configuration line vs. live round-trip with latency and key validation) plus its cost implication and default.

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?

Opens with a specific verb+resource ("Check connectivity to all NLQueries dependencies") and then enumerates the four checks, so an agent knows exactly what the tool reports on. It is clearly distinguishable from siblings like query, list_connectors, or invalidate_cache, none of which are diagnostics.

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 framing as a connectivity/dependency check makes the use case obvious, and the per-check breakdown tells the agent what a call will actually exercise. It stops short of naming when not to use it or which sibling to prefer for related diagnostics, so it is clear context rather than explicit routing.

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?

With no annotations, the description carries the full burden and does substantial work: it discloses that the agent may produce SQL or search documents, that explain appends route/cache/knowledge/check/timing provenance, and that paraphrase yields a deterministic non-LLM rendering of the SQL. It omits safety profile (read-only vs. arbitrary SQL execution), permission requirements, and rate limits.

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

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

Front-loaded with the core action, then structured Args/Returns sections with no filler. Slightly long, but each line adds information an agent needs, particularly the dialect enumeration and the explain/paraphrase distinctions.

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

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

Covers purpose, all parameters, and behavioral nuances for a 5-param tool with no annotation coverage. Although an output schema exists (making the Returns section partly redundant), the description's extra detail about what the formatted string contains is consistent and 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%, yet the description documents all five parameters: question with an example, agent_id with a discovery pointer, dialect with default and the full set of supported values, plus the semantics of explain and paraphrase. This fully compensates for the empty 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?

States a specific verb and resource ('Ask a natural-language question to an NLQueries agent') and immediately clarifies the mechanism (SQL translation or indexed-document search). It is clearly distinguishable from siblings like get_query_history, list_agents, and 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?

The description points to list_agents() for discovering agent_id, which is useful routing guidance, but it never states when to prefer this tool over alternatives (e.g. get_query_history for past queries) or any exclusions/limits. Usage is implied rather than prescribed.

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.