get_companyconcept

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

Annotations already cover readOnly/openWorld, and the description adds genuinely non-obvious behavior: values are passed through unchanged in SEC order, taxonomy/concept are case-sensitive and syntax-checked only, missing concepts surface as NOT_FOUND, and precision loss is handled by emitting the SEC's text with a numbers_as_text index. That is substantial disclosure beyond the annotations, though nothing is said about pagination or size limits for large concepts.

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 statement, then three short paragraphs each covering a distinct behavior. Every sentence carries information; the only mild cost is that the parenthetical syntax note and the precision note are dense without examples.

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 need not be explained, and the mutation/safety profile is covered by annotations. Still missing for a 3-required-parameter XBRL tool: what a valid taxonomy looks like, how cik_or_ticker is resolved, and any hint about response size for concepts with many observations.

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%, so the description must carry parameter meaning; it does so well for taxonomy and concept (verbatim insertion into the SEC address, case sensitivity, syntax-only validation) but says nothing about cik_or_ticker beyond the name, and gives no examples of valid taxonomy values.

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 — the SEC companyconcept document for one company and one concept — and states the scope ('every unit and every observation, in the SEC's order'), which is enough to distinguish it from get_companyfacts (all concepts for a company) in practice. It never names that sibling explicitly, so the differentiation is implicit rather than stated.

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?

There is no when-to-use guidance and no routing to alternatives such as get_companyfacts or get_frames, despite those siblings covering adjacent XBRL retrieval. The only conditional mentioned is an error outcome ('A concept the company never reported is NOT_FOUND'), which is behavior, not usage guidance.

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