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

As annotations já cobrem readOnlyHint/idempotentHint/destructiveHint; a descrição acrescenta que itens avulsos caem em '(sem cliente)' e que o agrupamento é via processo vinculado, além de especificar o formato de data. Isso enriquece o comportamento esperado sem contradizer as annotations.

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?

A descrição é organizada em definição, lista de ações e marcação flattened, mas repete o conteúdo das duas ações mesmo quando só por_cliente se aplica ao tool atual. Essa redundância é leve, porém poderia ser mais direta: 'Retorna a agenda por cliente (date_from/date_to em AAAA-MM-DD)'.

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?

Em um tool read-only de listagem com 2 params e sem output schema, a descrição cobre tipos de itens, agrupamento, janela de datas e buckets para itens avulsos. Faltam detalhes sobre ordenação, paginação ou estrutura do retorno, mas o essencial para uso correto está presente.

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?

Os params date_from/date_to têm 0% de cobertura no schema, então a descrição precisa compensar; ela informa que são uma janela de datas no formato AAAA-MM-DD. Não detalha se o intervalo é inclusivo nem o comportamento de datas invertidas, mas já dá o essencial para chamadas corretas.

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?

O nome e o final '[Flattened action: por_cliente]' definem o recorte: agenda do Astrea agrupada por cliente. A descrição lista os tipos (HEARING, EVENT, DEADLINE, TASK) e distingue da variante global, embora use 'Agenda' como substantivo e apresente as duas ações, o que exige atenção do agente até o final.

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?

A seção 'Ações' contrasta global (todas as atividades em uma janela de datas) com por_cliente (atividades agrupadas pelo cliente via processo vinculado), deixando claro o contexto de uso. Não recomenda explicitamente 'use astrea_agenda_global quando precisar de lista única', mas a distinção entre as duas listas cumpre a orientação.

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