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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond them: it returns ids intended for `fetch`, it only searches FirmTape's own public pages and finished sessions, and results are keyword-ranked rather than exhaustive. It stops short of describing result volume or pagination.

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 critical scoping and routing information is front-loaded, and the sentence about preferring structured sibling tools is the highest-value line. It runs long at five sentences with some overlap between the "prefer the specific tools" and "Not for" clauses, so it is slightly denser than necessary.

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 no output schema, the description correctly explains the return contract (ids to pass to `fetch`) and the corpus limits, ranking method, and date handling. The remaining gap is operational detail such as result counts or pagination, which an agent might want for a ranked keyword search.

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 100% but the schema's own parameter note is thin ("A topic, a question, or a trading date"). The description compensates by giving concrete accepted date forms ("2026-08-24", "August 24 2026", "August 2026") and explaining that a date resolves to that session or sessions, which the schema alone does not convey.

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 a specific verb+resource ("Search FirmTape") and narrows the corpus to documents about SPX dealer positioning: explainer pages, dated research measurements, and finished session archives. It distinguishes itself from the sibling tools by naming them and stating what they return instead (structured numbers vs. documents).

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?

It gives explicit routing guidance: clients able to call specific tools should prefer list_sessions / get_session / get_levels / get_level_history / screen_sessions, and it adds a dedicated "Not for" clause covering fetch and nameable-date measurements. Both when-to-use and when-not-to-use are stated with the alternative named.

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