ask_entity

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

With no annotations, the description carries the full burden and does disclose meaningful traits: the answer is grounded in the entity's passport with 'no guessing' and includes a passport_hash plus an optional verifiable registry signature. However, it says nothing about auth requirements, rate limits, latency, or failure behavior on an unknown domain, so coverage is partial.

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?

Three sentences, front-loaded with the defining constraint (answers come ONLY from one entity's registry facts), followed by provenance details and usage examples. No filler, though the provenance sentence is slightly dense.

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?

An output schema exists so return values need not be enumerated, yet the description still summarizes the payload (passport_hash, registry signature). Combined with the grounding guarantee and usage examples, an agent has enough to invoke it, with only parameter-level detail for 'question' left thin.

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 0%, so the description must compensate. It clarifies that 'domain' refers to a known entity domain and that 'question' is a natural-language question, but it adds no format constraints, syntax, or examples per parameter, leaving both fields only lightly specified.

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 verb+resource: asking a question that is answered ONLY from a specific entity's registry facts, grounded in that entity's passport. It implicitly distinguishes itself from siblings like search_registry and get_facts via the 'known domain' and 'ONLY from that entity' framing, though it never names an alternative directly.

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?

It gives concrete usage examples ('what does X do / what is X's refund policy') and scopes them to a known domain, which tells the agent when this tool applies. It stops short of explicitly stating when NOT to use it or naming search_registry/get_facts as the alternative for discovery-style queries.

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