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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the snapshot is served from a specific R2 file, has the same truth as a public HTML/JSON-LD twin, and no ad-hoc enrichment is performed. This goes beyond the annotations by clarifying source and consistency.

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 description is three tightly packed sentences, each earning its place: first sentence states the action and content, second establishes truth equivalence, third explains the backend and constraint. No filler, jargon overload, or repetition of schema fields. Front-loaded with the core verb and resource.

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?

Given the existence of a full output schema and comprehensive annotations, the description covers key contextual aspects: what the snapshot contains, its relationship to the public twin, and the serving mechanism. The only minor gap is the lack of guidance on when to use this vs sibling tools, but with an output schema present and all parameters documented, the description is largely complete.

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% – every parameter has a clear description in the input schema. The tool-level description does not add further meaning to any parameter (e.g., it does not elaborate on the slug or country formats beyond what the schema provides). Baseline 3 is appropriate because the schema already does the heavy lifting.

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 specific verb 'Read' and a precise resource 'materializer snapshot entia.entity_home_projection.v1'. It clearly states the snapshot contains 'claims + projection + policy' and links to the public twin. This level of specificity leaves no ambiguity about what the tool does, and the implementation detail 'no ad-hoc MCP enrichment' further sharpens the scope.

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?

While the description implies the tool is suitable for obtaining the canonical projection snapshot, it does not explicitly state when to prefer this tool over sibling tools like get_entia_home or get_full_dossier. There is no mention of exclusions or alternative tools, leaving the agent to infer usage context from the tool name alone.

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