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 does so richly: it discloses it performs no geocoding/searching, that DocuGIS2 cannot be fed via URL, the host-dependent return path (embedded TSV with copy button vs. text + webUrl), and the non-obvious rule that DocuGIS2 silently drops rows whose date is empty or a bare year.

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 purpose, then sources, then the delivery/paste workflow, then an Args section. It is long, but with 0% schema coverage and no annotations nearly every sentence is load-bearing, and the Args block is cleanly scoped per parameter.

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, yet the description still usefully frames what comes back (TSV plus webUrl) and who completes the final step. For a tool whose real action happens in an external UI, nothing an agent needs to call it 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 coverage is 0%, and the description compensates thoroughly: it documents required fields (name, x, y), optional fields (date, text, arbitrary keys becoming popup columns), alias handling (lng/lon/經度, lat/緯度, 地名), a concrete example, and the exact semantics of include_dates and max_rows.

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 ('Put places on a map in DocuSky's own DocuGIS2 tool') and immediately frames what it produces (the TSV DocuGIS2's import box accepts). The explicit 'does no geocoding and no searching' boundary cleanly separates it from siblings like 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?

Explains exactly when to reach for it and where coordinates come from (user, placeInfo from search_documents, gazetteer, own knowledge), and gives a clear when-not: never invent coordinates, leave the row out or ask the user. It also names the downstream alternative path (MCP Apps hosts vs. other hosts) and the human paste step.

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, and it does substantial work: it discloses the exact return structure per facet, the meaning of facet codes, and the conditional `webUrl` behavior for OPEN databases with MCP Apps rendering. It omits auth/permission requirements and any statement that the operation is read-only, which is the main remaining 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?

Front-loaded with the one-line purpose, then return shape, then cross-tool relevance, then args — a clean structure with no filler sentences. It runs somewhat long for a five-parameter tool, but each block carries information the agent needs.

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?

Params are fully documented, the return layout is described even though an output schema exists, and the webUrl/host-rendering nuance is captured. Missing only the operational context an unannotated tool would normally need, such as auth state and the fact that this is a non-mutating read.

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 the Args section documents all five parameters — including non-obvious sentinel values (".all" for the whole database, "[ALL]" for corpus) and the OPEN/USER target distinction. The owner_username entry ("when applicable") is vague about which target or sharing mode triggers 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?

States a specific verb and resource: breaking a query's hits down by DocuSky post-classification facets, with a concrete description of the output shape ([value, count, count] per facet). It also positions itself relative to siblings by noting that its facet codes feed twodim_analysis's dim1/dim2 arguments, so an agent can place it in the tool family without opening another 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?

"The quickest way to see how a term is spread across a database" gives a clear usage condition, and the twodim_analysis cross-reference tells the agent how this tool's output feeds a downstream call. However, it never contrasts itself with sibling analysis tools like word_cloud or tag_analysis, so the agent must infer which breakdown tool to pick.

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 behavioral burden. It discloses return shape, deliberate omission of full text, excerpt behavior, pagination parameters, and that OPEN databases return a webUrl rendered by MCP Apps hosts. It does not mention authentication or permission requirements, but the read-only search nature is 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?

The description is front-loaded with the core purpose and then structured with a clear Args section. Despite being longer due to eight undocumented parameters, every sentence earns its place by adding search semantics, output behavior, or parameter meaning. There is no wasted or repetitive 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?

Given eight parameters, 0% schema coverage, and an output schema, the description is complete enough for correct invocation. It explains all arguments, the excerpt/full-text distinction, and the public webUrl behavior. The output schema can carry return-value details, and the remaining auth context is not essential to call the search 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 must compensate for all eight parameters. It does so thoroughly: it defines db, query with `+term`/`-term`/`.all` syntax, corpus `[ALL]`, 1-based page, page_size 1-100, target OPEN/USER, excerpt_chars with 0 disabling excerpts, and owner_username for friend-shared databases. This adds substantial meaning beyond the bare schema titles and defaults.

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 first sentence states a specific verb, resource, and scope: full-text search of one DocuSky database returning metadata plus a short excerpt. It immediately distinguishes itself from get_document by explaining that full document text is deliberately omitted. An agent can tell exactly what this tool does without opening other schemas.

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 routes full-document reading to get_document with a hit's `n` and matching db/corpus/query/page_size. It also explains query syntax and target modes, giving clear context for when to use this search tool versus the full-document alternative. Nothing important is left to 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, so the description must carry the full burden. It discloses a key behavioral trait: returns empty for untagged databases. It also explains the OPEN-database side effect (webUrl to docusky.org.tw, rendered in MCP Apps-capable hosts). It does not discuss read-only nature, permissions, or rate limits, but 'Summarize' implies a read 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?

Front-loaded core purpose, followed by meaningful preconditions and the OPEN/webUrl caveat, then an Args block. Efficient overall, though the webUrl/MCP Apps aside could be trimmed for some hosts.

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, preconditions, side effects, and parameter semantics, which is substantial for a 5-param tool with 0% schema coverage. An output schema exists, so return-value details are not required. It could go slightly further on parameter usage (owner_username conditions) and target semantics, but 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?

Schema coverage is 0%, so the description must document all 5 params — and it mostly does: db, query (with '.all' sentinel), corpus ('[ALL]' sentinel), target ('OPEN'/'USER'), and owner_username ('when applicable'). The sentinel values and enum-like values for target are essential semantics the bare schema lacks. Minor gap: no guidance on when owner_username applies beyond 'friend-shared database'.

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 (Summarize) and resource (DocuXML tags: people, places, dates, custom markup), scoped to a query's hits. The parenthetical enumeration of tag types makes the resource concrete and distinguishable from sibling analysis tools like word_cloud or twodim_analysis.

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 it is meaningful ('only meaningful for databases whose documents carry inline tagging') and what happens otherwise ('returns an empty result otherwise') — a clear precondition. However, it doesn't compare itself to sibling analysis tools (word_cloud, twodim_analysis), leaving the agent to infer which analysis tool to pick.

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 so well: it discloses that the endpoint is EXPERIMENTAL (added 2026-01-28), that live testing on 2026-09-11 found it rejects every pair tried, the exact error shape returned, and that DocuSky's own UI is not wired up. This is unusually rich behavioral context beyond any structured field.

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?

Purpose is front-loaded and the Args block is cleanly structured. The experimental warning is longer than typical but each sentence carries decision-relevant information (date, error payload, alternative workflow), so the length is largely justified rather than 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?

For a 7-parameter, 3-required tool with an output schema already present, the description covers purpose, prerequisites, parameter meanings, and failure behavior comprehensively. Nothing an agent needs in order to either call it correctly or decide to avoid it 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: the Args block documents all seven parameters, adding meaning the schema lacks (dim1/dim2 as keys from post_classification's 'facets', query '.'all' for the whole database, corpus '[ALL]', target 'OPEN'/'USER' values absent from the schema's enum-less properties). A few entries (db, corpus, owner_username) remain thin, so it falls 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?

The first sentence gives a specific verb and resource ('Cross-tabulate a query's hits by two DocuSky classification facets at once'), which distinguishes it cleanly from sibling analysis tools like tag_analysis and word_cloud. An agent can identify the operation 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 prescribes the prerequisite workflow ('Call post_classification first to see which facet codes exist') and warns about the expected failure mode and the condition under which the tool is unusable. This is exactly the when-to-use / when-not-to-use guidance an agent needs.

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 delivers well beyond the schema: it discloses the webUrl return, inline-vs-link rendering by host, extra bubble/bar/table views and Save, the random-subset caveat for large lists, term rewriting of commas/semicolons, and URL-length trimming.

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 progressively deeper detail; the Args block repeats the schema shape but earns its place through added semantics. Slightly long (the 'takes numbers you already have' sentence is near-redundant with the no-counting line), but nothing is filler-critical.

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 only 2 params and an existing output schema, the definition covers purpose, upstream data contracts, return behavior, rendering differences, and the practical term-count/URL-limit caveats an agent needs to build a working call. 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 does: it gives the terms shape (term -> weight) with an example, requires positive weights, explains proportional rescaling of non-integers, documents the separator-stripping behavior, and states max_terms default 150 plus secondary trimming for DocuSky's URL limit.

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 ('Draw a word cloud of term frequencies') and pins down the engine (DocuSky's WordCloudLite). It explicitly distinguishes itself from siblings by asserting 'This tool does no counting and no searching of its own', separating it from tag_analysis, search_documents, 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?

Names the concrete upstream sources (tag_analysis counts, post_classification value/docCount pairs, terms counted from get_document) so the agent knows the correct pipeline position, and rules out using it for counting/searching. It does not name any alternative visualization tool, but the when-to-use condition is clear.

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