Get Data Model

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

With no annotations, the description carries the full burden and does so well: it declares the tool is public with no authentication needed, and describes the two distinct behavioral modes (no table → index of ~110 tables; table specified → full table with keys, indexes and referencedBy). The only gap is that it never explicitly frames the operation as read-only, though 'get' plus 'public' makes it near-unambiguous.

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, then bulleted by call mode, then the usage guidance — a clean, scannable structure with little filler. The bullets restate return shapes that the output schema already covers, which is mild redundancy, but it usefully disambiguates the two modes rather than merely echoing field names.

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 one-parameter, read-only metadata tool this is complete: it covers scope, authentication, both call modes, expected scale, and the downstream workflow it feeds. Nothing an agent needs in order to call it correctly or route to a sibling 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 single 'table' parameter has no description, but the description fully compensates by spelling out both branches — omitted yields the table index, and a concrete example ('arm_or_cohort') shows the expected value format. An agent can construct a correct call from the description alone.

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 — 'Get the ImmPort data model' — and immediately enumerates what the resource contains (tables, columns, types, descriptions, keys, joins), tying it to the concrete artifacts it describes (Tab.zip / MySQL release files). It is clearly distinguishable from siblings like lookup_controlled_vocabulary and from the immport://data-model resource, which it names as a different scope.

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 when-to-use conditions: understand what a column means, find columns holding controlled values, and plan joins before writing SQL or analysing release files. It also names the alternative for each adjacent need — lookup_controlled_vocabulary for actual values and immport://data-model for the entity/endpoint overview — so the agent has no inference to do.

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