twodim_analysis

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.