Read the trust score

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: required scopes (analytics:read, luca:read), redacted data sensitivity, and the fact that the default workspace comes from the environment and can be overridden. It does not explain what the auto-send gate flag means or how rates are computed.

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 substantive content (what metrics, over what period) is front-loaded in the first sentence, with operational metadata following in short labeled lines. The scope and endpoint lines are boilerplate but each conveys an actionable constraint; nothing is redundant enough to obscure the payload description.

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 an output schema present, return-value explanation is unnecessary, and the annotations carry the safety profile. The description covers auth requirements, data sensitivity, idempotency, and workspace targeting, leaving only the semantics of the channel filter and the gate flag unspecified — minor for a read-only analytics endpoint.

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 67%, so the schema documents the UUID/slug parameters while the nested query object's period and channel enums carry no descriptions. The description clarifies that workspaceId/workspaceSlug override the environment-configured default, which is meaningful context the schema lacks, but it never mentions the channel filter or how period interacts with the returned rates.

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 the concrete metrics returned — draft approval, edit, and rejection rates plus the auto-send gate flag — which is far more specific than the title 'Read the trust score'. It also pins the endpoint (GET /api/analytics/trust-score), so an agent knows this is a read of trust metrics rather than lead scoring or benchmarks. It stops short of explicitly contrasting itself with the similarly named luca_analytics_lead_score.

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 context is implied ('for a period', the period enum in the schema, and the workspace override instruction) but there is no explicit statement of when to pick this over sibling analytics tools such as lead_score or benchmarks. The workspace override sentence is genuine guidance, but it addresses targeting rather than tool selection.

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