Export Ontology

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds useful context by indicating this returns the complete layer in a single document (not a filtered subset) and that it is serialized as YAML/JSON, but it says nothing about size limits, permission requirements, or behavior when the datasource argument is omitted despite multiple datasources being registered.

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 dense sentence that front-loads the resource and scope before the parenthetical inventory of included sections and the closing use case. Every element earns its place, with only minor overhead from the long parenthetical list; the phrase is a noun fragment rather than an explicit verb statement, which is a small structural weakness.

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 an output schema present and only two optional parameters at full schema coverage, the description carries little burden and covers the main open questions: what is exported, in what format, and for what purpose. The only meaningful gap is what happens when 'datasource' is null and several datasources exist, which neither the description nor schema resolves.

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 100%, with both the 'format' enum and the optional 'datasource' parameter already documented in the schema, including the single-datasource default behavior. The description confirms that the document covers exactly one datasource and that formats are YAML/JSON, but adds no syntax or format-selection guidance beyond what the schema provides, so baseline 3 applies.

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 names a specific resource and scope: 'the whole semantic layer of a datasource as one YAML/JSON document', and enumerates what is included (Terms, column mappings, SQL attributes, relationships, glossary, example queries). This clearly separates it from retrieval tools like get_term or search_ontology, though it never explicitly names export_wiki or import_ontology as the adjacent alternatives.

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 trailing clause 'for review or version control' implies the intended use case, so an agent can infer this is a full-dump/backup operation rather than a targeted lookup. However, there is no explicit when-not guidance and no routing statement telling the agent to prefer export_wiki for wiki output or import_ontology for the reverse operation.

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