Args:
    query: termos de busca (ex: "dano moral atraso voo").
    limite: numero maximo de resultados (1-50). Padrao: 10.
    tribunal: filtra por sistema de tribunal. Valores: "STF", "STJ", "TST",
        "TJs" (todos os TJs), "TRFs", "TRTs", "TSE", "STM", "TCU". Aceita varios
        separados por virgula (ex: "STJ,STF"). (Filtro de tribunal especifico,
        tipo TJ-PI isolado, nao e suportado por este filtro de topo.)
    tipo: tipo de julgado. Valores: "acordao", "sumula", "decisao"
        (monocratica), "sentenca", "despacho", "orientacao".
    periodo: recorte de data por periodo recente. Valores: "7dias", "30dias",
        "365dias" (ou apelidos "ultima semana"/"ultimo mes"/"ultimo ano", ou um
        numero de dias). Obs.: o JusBrasil filtra por periodo relativo, nao por
        data inicial/final exata.
    ordenacao: "data" (mais recentes) ou "relevancia" (padrao).

Returns:
    Lista de dicts com titulo, tribunal, numero_cnj, data, ementa, url.

Use APOS `buscar_jurisprudencia` para montar citacoes completas em peticoes.
A busca da ementa curta; use esta tool para pegar os dados formais
(relator, orgao julgador, data de julgamento) da decisao que voce quer citar.

IMPORTANTE - ANTI-ALUCINACAO:
- Se qualquer campo retornar None/vazio (especialmente `ementa`), NUNCA invente
  nem reconstrua o conteudo com base em memoria ou conhecimento geral.
- Campos nulos indicam FALHA DE EXTRACAO ou AUSENCIA REAL no JusBrasil,
  nao sao convite para preencher com texto plausivel.
- Verifique sempre o campo `_parse_warnings` no retorno. Se ele existir, siga
  estritamente suas instrucoes e comunique ao usuario.
- Para uso em peticao, oriente o usuario a conferir o texto oficial
  diretamente no site do tribunal (scon.stj.jus.br, sites dos TJs, etc.).
- JusBrasil eh agregador privado, NAO eh fonte oficial para citacao formal.

Args:
    url: URL da decisao (ex: "https://www.jusbrasil.com.br/jurisprudencia/tj-pi/1629196340").
         Pegue a URL do campo `url` retornado por `buscar_jurisprudencia`.

Returns:
    Dict com:
    - titulo, tribunal, tipo (Apelacao Civel, etc.)
    - numero_cnj (formato 0000000-00.0000.0.00.0000 pronto pra citacao)
    - relator, orgao_julgador, data_julgamento, data_publicacao
    - ementa (texto completo)
    - citacao_abnt: string ja formatada estilo "(TJ-PI - Apelacao Civel: NNN, Relator: ..., ...)"

Args:
    query: termos de busca (ex.: "negativacao indevida", "dano moral").
    limite: numero maximo de resultados (1-50). Padrao: 10.
    tribunal: opcional — filtra por sistema de tribunal ("STJ", "STF", "TST", ...).

Returns:
    Lista de dicts com titulo, tribunal, numero_cnj, data, ementa, url.

Diferente de `ler_decisao` (que traz so metadados + ementa), esta tool retorna
o inteiro teor do julgado. EXIGE login (credenciais configuradas no Keychain);
sem sessao autenticada o conteudo nao vem.

IMPORTANTE - ANTI-ALUCINACAO:
- Se `texto` voltar nulo/vazio, NUNCA invente o conteudo do acordao. Significa
  que o inteiro teor nao esta disponivel no JusBrasil para esta decisao, ou que
  a sessao nao esta autenticada. Informe o usuario e oriente a consultar o
  inteiro teor no site oficial do tribunal.
- Verifique `_parse_warnings` no retorno e siga suas instrucoes.
- JusBrasil eh agregador privado, NAO eh fonte oficial para citacao formal.

Args:
    url: URL da decisao (ex.: ".../jurisprudencia/tj-pi/1629196340") OU a URL
         direta de inteiro teor (".../inteiro-teor-NNN").

Returns:
    Dict com url, url_inteiro_teor, texto (texto integral), n_caracteres,
    autenticado (bool).

Para cada URL, monta uma secao com a citacao formatada, a ementa, o link de
verificacao (JusBrasil) e, se pedido, o inteiro teor. Use depois de escolher,
com `buscar_jurisprudencia`/`buscar_sumulas`, quais decisoes quer reunir.

Args:
    urls: lista de URLs de decisoes/sumulas (campo `url` das buscas).
    incluir_inteiro_teor: se True, inclui o texto integral de cada decisao
        (mais lento; exige login e nem toda decisao tem inteiro teor).
    titulo: titulo do dossie (padrao: "Dossiê de Jurisprudência").
    caminho: caminho .docx de saida (padrao: ~/Downloads/<titulo>-<data>.docx).

Returns:
    Dict com arquivo (caminho salvo), n_itens, n_falhas, com_inteiro_teor.