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

With no annotations, the description carries the behavioral burden and does well: it frames the tool as a passive diagnostic that reports status rather than mutating anything, and confines its relevance to a specific failure condition. It does not mention possible side effects or latency of the credential check, but the report-only framing adequately signals a safe read.

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 short sentences, front-loaded with what it does and followed immediately by the condition for running it. No filler or repetition of schema 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?

An output schema exists, so return values need no explanation, and with zero parameters the only remaining need is invocation guidance, which the description fully supplies. Nothing an agent requires 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond the schema. Baseline 4 applies with no parameter 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 states a specific operation (report credential configuration and validity) against a specific resource (DocuSky credentials). It is clearly distinguishable from the data-oriented siblings like list_databases and search_documents.

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 gives explicit when-not-to-use ("Public databases need no login") and a precise trigger for when to run it ("only when private ('USER') databases are unreachable"). This is a textbook scoping rule an agent can act on without inference.

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 full burden, and it does disclose the key traits: results are a single hit, long bodies come back in slices, and paging is done by raising offset by max_chars. It also notes include_raw_xml returns the untouched DocuXML. It leaves auth/permission behavior (e.g. what OPEN vs USER target implies) implicit.

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 essential constraint (matching search parameters) before the parameter list, and the pagination mechanic is given its own compact sentence. The Args block duplicates some parameter names already visible in the schema, but overall it is tight and earns its length.

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-value documentation is not needed, and the description correctly focuses on the coupling to search_documents and on slice-based paging. The one gap is that permission/access semantics for target and owner_username are left unstated.

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% across 10 params, yet the Args block explains every one, with real added meaning for result_number ('global 1-based rank…the n field of a search_documents hit'), offset ('character offset into the document body'), max_chars, include_raw_xml and target ('OPEN' or 'USER'). Some entries are thin restatements (db = 'Database title', page_size = 'the same one'), which keeps this short of 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?

States a specific verb and resource ('Fetch the full text of one search hit') and immediately delimits the retrieval mode to a single ranked result, which cleanly separates it from the sibling search_documents. The identifying key (position in the result set) is named in the first sentence.

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 the precondition that db, query, corpus and page_size must match those that produced the hit, 'or the ranking will not line up', and names search_documents as the producing tool. It does not positively state when not to use this tool, but the prerequisite guidance 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 carries the full burden. 'List' implies a non-destructive read and it discloses the conditional constraint that include_friend_db applies only to USER target, but it says nothing about authorization needs, scope of returned data, 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?

One summary sentence plus a compact Args block; front-loaded with the operation and scope and nothing redundant. The structure is efficient though not especially polished.

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 an output schema exists, return-value detail is unnecessary, and the description adequately covers all three parameters and their interplay. The only material gap is sibling routing and any environment/auth preconditions.

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 and largely does: it gives the accepted values for 'target' (OPEN/USER), explains include_friend_db's effect and its USER-only restriction, and defines 'db' precisely. It does not restate the schema defaults, which is fine.

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 (List) and resource (corpora) and scopes it to 'inside one database, with document counts', which separates it from list_databases at the parent level. It does not explicitly name a sibling it is not, so it falls short of a 5.

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?

Usage is implied through the prerequisite that 'db' must be 'exactly as returned by list_databases', which tells the agent the correct call ordering. However, there is no explicit when-to-use/when-not or routing against siblings like search_documents or list_databases.

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 conveys read-only listing semantics and hints at authentication via 'logged-in account', but does not state permission requirements, friend-sharing implications, or result limits. Partial disclosure 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?

Front-loaded one-line purpose followed by tight per-argument notes; no filler. The 'Args:' block is compact and each line 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?

With only two optional parameters, an output schema covering return values, and explicit parameter meanings, an agent has what it needs to invoke the tool. Minor gaps in auth/permission context remain but are low-impact.

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 it does: it explains the meaning of both the 'target' enum-like values ('OPEN' vs 'USER') and the 'include_friend_db' flag including its USER-only constraint. This is meaningfully 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 states a specific verb and resource ('List DocuSky databases available to this server') with a clear scope. It is distinguishable from the closest sibling list_corpora by naming a different resource type, though it does not explicitly contrast against it.

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 implies when to use each mode by explaining that target='OPEN' yields public databases and 'USER' yields the account's own, which is useful selection guidance. However, it gives no explicit when-to-use versus alternatives or prerequisites beyond that.

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 does disclose the return shape (per-facet distribution of [value, document count, hit count]), which is meaningful. However, it omits read-only/permission behavior, error conditions, and what the facet set actually contains beyond a vague ellipsis.

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?

Purposes are front-loaded, followed by return format and an arg list. The structure is clean and each section pulls weight, with only mild redundancy in the arg explanations.

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?

Because an output schema exists, the description needn't explain return values, yet it helpfully summarizes them. Parameters are all covered. It stops short of permission requirements or sibling routing, but for a facet-distribution tool this is nearly 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?

Schema coverage is 0%, so the description must carry parameter meaning — and it does, documenting all five: db, the '.all' query sentinel, corpus with '[ALL]', target accepting 'OPEN'/'USER', and owner_username for friend-shared databases. That is strong compensation, though enum-style constraints are only hinted, not formalized.

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 opening sentence gives a specific verb and resource — breaking a query's hits down by post-classification facets — and goes further by naming the facets (corpus, period, place, category). It distinguishes itself from sibling retrieval tools like search_documents or tag_analysis by framing the output as a distribution rather than a hit list.

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 'the quickest way to see how a term is spread across a database' implies when the tool is valuable, but no alternative tool is named and no explicit when-not/exclusion is given. Usage 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, the description carries the burden and does disclose key behavior: results are excerpt-only, excerpts are controlled by excerpt_chars (0 disables them), and pagination is 1-based with a 1-100 page_size bound. It does not state permission/auth requirements or read-only nature beyond the friend-shared `owner_username` hint, so it stops short of full transparency.

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 core behavior and the get_document hand-off are front-loaded in the first two sentences, followed by a compact structured Args block. Every line carries information an agent needs; nothing is restated from the name or schema.

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 an 8-parameter search tool with an output schema available, the description supplies everything else needed to call it correctly – query syntax, corpus/db scoping, pagination, excerpt control, and the pointer to get_document for full text. Nothing material 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 it does: query syntax is documented ('+term' requires, '-term' excludes, '.all' matches everything), corpus accepts '[ALL]', target is 'OPEN' or 'USER', page is 1-based, page_size is 1-100, and owner_username is scoped to friend-shared databases. All 8 parameters gain meaning absent from 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?

States a specific verb and resource ('Full-text search one DocuSky database') plus the return shape ('metadata plus a short excerpt per hit'), which immediately separates it from get_document and the listing siblings. An agent can identify the tool's role 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?

It explicitly routes the agent: full text is omitted here, so 'call get_document with a hit's `n` (and the same db/corpus/query/page_size)' to read one in full. That is a concrete when-to-use-this vs when-to-use-the-alternative condition rather than implied 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 exist, so the description carries the full behavioral burden. It usefully discloses the empty-result outcome for untagged databases, but says nothing about permissions, whether filtering by owner_username requires a share relationship, or what the summary contains.

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-loads the purpose in one sentence, then the key caveat, then a compact Args list. Nothing is padded, though the Args block is essentially a plain list rather than prose that adds interpretation.

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-value detail is not required. With five parameters at 0% schema coverage, the glosses plus the inline-tagging caveat cover most of what an agent needs; only the meaning of target and the sharing/permission model for owner_username are left implicit.

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: it glosses db, query (including the '.all' sentinel), corpus (including '[ALL]'), target's two allowed values, and owner_username's conditional relevance. The target values remain opaque ('OPEN' vs 'USER' is not explained), leaving a small 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+resource combination ('Summarize the DocuXML tags ... in a query's hits') and enumerates what counts as a tag (people, places, dates, custom markup). An agent can distinguish it from list_databases or search_documents by resource, though no sibling is named explicitly.

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 gives a real exclusion condition: 'Only meaningful for databases whose documents carry inline tagging; returns an empty result otherwise.' That tells the agent when not to expect value, but it never names an alternative tool for untagged databases or non-tag analyses.

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