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

Annotations only declare read-only/idempotent/non-destructive; the description goes well beyond by disclosing entitlement truncation (first 5 rows in full plus locked.count and locked.by_type, never the rows), that contact values and decision-maker names are never returned, and that every answer reports what it withheld in `entitlement` and `locked`. This is exactly the kind of behavioural context structured fields cannot carry.

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 card definition, then filtering, then access rules, which is a sensible order. However, the card-contents enumeration is a long comma-chained list and the closing promotional line ('7 days free at https://...') does not help an agent invoke the tool correctly.

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?

For a 10-parameter, no-output-schema, complex tool, the description covers the return shape (card fields), the entitlement/locked contract, and the access tiers, which is what an agent most needs. It is only thin on how the audience-side parameter relates to the card's audience section.

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 60%, so several parameters are self-documented (query, since, cursor, family, subject_dfx_id, affected_dfx_id). The description echoes the filterable dimensions but adds no syntax or format detail for limit, cursor, include_audience, or affected_dfx_id, so it neither compensates for the gap nor exceeds the schema meaningfully.

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 states a specific resource ('the governed signal layer the site ranks by', published signal cards) and enumerates what each card contains, so an agent can tell this is a signal-card search distinct from raw ledgers like get_forward_signal_ledger. It does not explicitly name a sibling to differentiate against, and the framing is heavy on domain jargon, so it stops short of a 5.

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?

Usage is only implied: 'Filter by family, domain, subject id, since date or minimum exposure' tells the agent what it can narrow on, but never states when this tool should be chosen over near neighbours such as why_now, who_should_care, changes_since, or get_forward_signal_ledger. No when-not or alternative routing is provided.

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