get_segments

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description adds real behavior beyond them: an edge case ('Returns empty `axes` when the issuer reported only the consolidated total') and a gating rule ('members of each axis need a paid plan... below it the axes are listed without them, with a note'). That is substantive, non-obvious disclosure; only error/pagination behavior is left out.

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 core purpose on line one, followed by usage examples, then edge cases and the plan caveat. Every sentence carries information; formatting with line breaks aids scanning. Slightly fragmentary prose but no filler.

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-shape explanation is not owed here, and the plan/empty-axes notes cover the two most surprising runtime behaviors. However, with four parameters at zero schema coverage and no explanation of how hub_concept_code is obtained, an agent has enough to understand the tool's role but not enough to invoke it confidently without consulting another tool.

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?

All four parameters (entity_id, hub_concept_code, fiscal_year, fiscal_period_type) have 0% schema description coverage, and the description supplies no per-parameter meaning, format, or valid values — 'hub_concept_code' in particular is opaque without a reference to search_concept/list_hubs. Only a loose hint about 'the given period' and 'a metric' gestures at two of the four.

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: 'Dimensional breakdown of a metric (axis/member from XBRL dimensions)' plus 'Reads the dimensional (segment) values for the given period.' An agent can tell this is the segment/axis dimension reader rather than a plain fact lookup. It stops short of naming the closest siblings (get_fact, get_fact_decomposition, roll_up_metric), so the boundary is inferable rather than explicit.

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 concrete trigger phrases — 'revenue par région', 'profit by segment', 'split by product/geography' — that map directly to user intent. It does not state when NOT to use it or name an alternative tool for non-dimensional facts, which the sibling set (get_fact, get_fact_decomposition) clearly contains.

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