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

With only readOnlyHint provided, the description carries the burden and does so by enumerating the returned analysis categories and adding genuine caveats: matched_by explains the matching strength, lobbying dollar totals are filing totals across every issue, and 10b5-1 sales are called out. It omits auth, rate limits, and failure behavior, so it is strong but not exhaustive.

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 core identity is front-loaded, but the body is one sprawling sentence that strings together a dozen return categories, making it dense to parse. Most of that enumeration is defensible given there is no output schema, yet the run-on structure hurts readability and could be broken into grouped clauses.

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 sensibly shoulders the burden of describing what comes back, and it covers the major data families plus interpretation notes (matched_by, filing-total caveat, the summarisation instruction). Only edge behavior (missing/invalid id, error cases) is left unaddressed.

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% for the single id param, so the baseline is 3; the description goes slightly further by stating the accepted id forms (HillSignal url/id or SAM.gov notice id) and the upstream tool that produces them, which reduces ambiguity about what to pass.

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+resource ('One SAM.gov notice as HillSignal analyses it') and makes the single-notice scope explicit, which cleanly separates it from the list-oriented sibling search_opportunities. An agent can tell what it fetches and how it differs from the search tool without opening any schema.

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?

Tells the agent exactly where the required id comes from ('Pass id from search_opportunities (hillsignal_url or its id) or a SAM.gov notice id'), which encodes the intended workflow. It stops short of explicit when-not-to-use guidance or stating when a search-then-get sequence is preferred over alternatives, so it is clear context rather than full routing rules.

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