Actor Intelligence

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds meaningful context beyond annotations: it discloses that this is a composite aggregating multiple data sources (profile + attribution correlations), implying heavier computation and cross-referencing. This helps set latency/completeness expectations that annotations alone don't convey.

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?

Single sentence, perfectly sized. It front-loads the core purpose ('Composite intelligence picture') and specifies the two key components delivered (profile + attribution correlations). Zero wasted words or filler. Ideal conciseness for a tool 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?

The tool has a rich output schema (true), full schema coverage (100%), and one required parameter. The description clearly states what the composite includes. For a read-only lookup tool of this complexity, the description plus annotations and output schema provide adequate completeness. It could potentially mention that the correlation component requires an established attribution graph, but this is minor given the output schema will clarify structure.

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 100% — the single 'name' parameter is documented as a 'Threat-actor name or alias (e.g. "APT29")' in the schema itself. The description adds marginal value by confirming the parameter is the actor identifier used to retrieve the composite picture, but it doesn't meaningfully extend beyond schema documentation. Baseline 3 is appropriate given full schema coverage.

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 uses a specific verb-resource phrase ('get_actor_intelligence' → 'Composite intelligence picture for a threat actor') and clearly states what it returns: 'full actor profile plus cross-actor attribution correlations'. It differentiates itself from siblings like get_malware_intelligence or get_campaign_intelligence by specifying this is actor-specific composite data, though it could more explicitly contrast with similar sibling tools.

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 implies when to use it ('in one call' suggests it's the consolidated/composite endpoint versus separate profile or correlation calls), but it doesn't explicitly state when NOT to use it or name alternate tools. Given siblings like get_attribution_evidence and explain_correlation exist, explicit guidance on when to choose this composite call over those granular correlation tools would strengthen this dimension.

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