domain_summary_tool

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

With no annotations provided, the description must convey the tool's behavior. It states it returns a summary, which implies a read-only operation, but it does not explicitly mention that it is non-destructive, any side effects, or permissions required. Given the read-only nature, a 3 is appropriate as it covers the essential behavior but lacks explicit guarantees.

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 concise and well-organized. It includes the purpose, parameter descriptions, return structure, an example, and a best practice—all in a compact format with no unnecessary verbiage. The structure is clear and easy to parse.

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 description covers the tool's purpose, arguments, return values, and a usage example, which is sufficient for a simple summary tool. It does not discuss error handling or edge cases, but these are not critical for the tool's primary function. The return structure is described in the 'Returns' section, making the output expectations clear.

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?

Both parameters are explained in the description: 'domain' is described as 'The domain to summarize' with examples, and 'example_limit' as 'Maximum number of examples to include for each state.' This provides sufficient meaning beyond the raw schema, though the concept of 'state' is not elaborated further.

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 clearly states the tool's function: 'Get a summary of entities in a specific domain.' It uses a specific verb ('get') and resource ('summary of entities'), and is distinct from sibling tools like list_entities or get_entity by focusing on aggregated summary data rather than individual records.

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 provides a specific best practice: 'Use this before retrieving all entities to understand what's available.' This gives clear guidance on when to use the tool, though it does not explicitly mention when not to use it or compare with alternative tools. The example also demonstrates typical usage.

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