whodb_platform_ontology_query

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

Goes well beyond the readOnly/idempotent annotations by disclosing non-obvious execution traits: the server scans at most scan_limit rows before filtering so totals may be partial, policy-protected ontologies reject the query, and results are further capped by the MCP --max-rows setting. These are exactly the behaviors an agent cannot infer from annotations or schema.

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 purpose and routing decision in the first two sentences, then progressively adds grammar and caveats. Information-dense with almost no filler, though the grammar examples and workspace note make it longer than strictly minimal.

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 13-parameter, nested-object query tool with no output schema, the description covers the critical gaps: scan/result capping semantics, group-by metric shape, access-control failure mode, and per-call workspace targeting. An agent has everything needed to call it correctly and to know when not to.

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 100%, so the baseline is 3, but the description adds value with concrete where-grammar examples ({"amount":{"gte":100}}, {"_or":[...]}) and the note that group_by + metrics return one row per group. It doesn't explain limit/offset interaction or sort aliasing beyond what the schema says, keeping 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 ('Query ontology rows') plus its capabilities (filters, search, joins, grouping, metrics), and immediately contrasts with the sibling whodb_platform_ontology_rows. An agent can distinguish this query tool from row-paging and from the aggregate tool without opening any 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 explicit positive routing ('Use this to answer data questions instead of paging through whodb_platform_ontology_rows'), a named alternative for exact totals (whodb_platform_ontology_aggregate), and a fallback path when policy-protected ontologies reject the query (whodb_platform_ontology_rows). When-to-use, when-not-to-use, and alternatives are all covered.

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