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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explains the as_of date semantics (in-force identifiers vs today's), the refusal behavior for ambiguous symbols and how prefer_country resolves it, the uneven history depth, and the per-source freshness metadata. This is exceptional transparency about edge cases and data quality.

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?

The description is dense and front-loaded, but it reads as a wall of text with several run-on sentences. Every sentence contributes information, yet the lack of structuring (e.g., bullets or short paragraphs) makes it harder to scan. It is slightly verbose but not padded.

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?

Despite having no output schema and no annotations, the description covers a remarkable amount: the kinds of identifiers returned, the distinction between security and issuer grain, the dated timeline, the private-graph bridge with confidence grade, ambiguity refusal, coverage statistics, and freshness caveats. This is a complete picture for a complex 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?

Schema description coverage is only 17%, so the description must compensate. It thoroughly explains as_of and prefer_country semantics (dated binding, candidate selection). However, the three include_* boolean parameters (include_history, include_private_graph, include_share_classes) are never explicitly described, leaving their effect on output ambiguous. Partial compensation only.

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 opens with 'IDENTITY CROSSWALK for one symbol,' clearly specifying the verb (crosswalk) and resource (identifiers for a security and issuer). It distinguishes itself from sibling reference tools by emphasizing the one-symbol scope and the separation of security-grain vs issuer-grain identifiers, making its purpose unmistakable.

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 description provides explicit use cases: 'Call it to join two data sets that key on different identifiers, to translate a CUSIP-keyed holdings file into tickers, or to find out what a symbol used to be.' It stops short of naming alternative tools explicitly, but the context is clear enough for an agent to decide when to invoke it.

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