Retorne resultados, erros e indicações de comportamento
Escolha entre erro de protocolo e erro de execução e descreva o comportamento com anotações.
- Diferenciar erros JSON-RPC de falhas durante a execução
- Retornar conteúdo útil para o modelo
- Configurar anotações sem tratá-las como garantias
Falhas de protocolo e falhas da ferramenta são situações diferentes:
| Erro de protocolo | Erro ao executar a ferramenta | |
|---|---|---|
| Exemplos | ferramenta desconhecida, solicitação malformada | API indisponível, data inválida, regra de negócio |
| Formato | error JSON-RPC, como -32602 | resposta normal com isError: true |
| Chega ao modelo? | pode não chegar | deve chegar para permitir correção e nova tentativa |
Anotações como readOnlyHint, destructiveHint, idempotentHint e openWorldHint ajudam o host a decidir quando pedir confirmação. Elas são afirmações do servidor, não provas de segurança.
1{
2 "jsonrpc": "2.0",
3 "id": 4,
4 "result": {
5 "resultType": "complete",
6 "content": [{ "type": "text", "text": "Data de partida inválida: use uma data futura." }],
7 "isError": true
8 }
9}Experimente
Até 15 XPQue tipo de erro?
Classifique cada falha como erro de protocolo ou erro durante a execução da ferramenta.
“O cliente chama a ferramenta inexistente “fly_to_moon””
“A data informada já passou”
“A API de clima excedeu o tempo limite”
“O corpo da solicitação não contém JSON válido”
“Não existe pedido com aquele número”
Indicações de comportamento: anotações
As ferramentas podem incluir anotações para ajudar o cliente a decidir o que confirmar com a pessoa usuária. Estas quatro indicações têm valores padrão cautelosos: readOnlyHint (false), destructiveHint (true), idempotentHint (false) e openWorldHint (true). As duas últimas indicações sobre efeitos destrutivos e idempotência só importam para ferramentas que não são somente de leitura. Anotações são declarações do servidor, não garantias de segurança.
Experimente
Até 15 XPAnote as ferramentas
Configure as quatro indicações para cada ferramenta e confira suas escolhas. Pense no que acontece quando a ferramenta é executada — e no que acontece se ela for chamada duas vezes.
search_docs
Pesquisa a wiki da empresa e retorna os títulos das páginas encontradas.
readOnlyHint (padrão false)
Apenas lê — sem alterar nada?
destructiveHint (padrão true)
Pode excluir, sobrescrever ou enviar algo?
idempotentHint (padrão false)
Chamadas repetidas têm o mesmo efeito de uma só?
openWorldHint (padrão true)
Pode acessar sistemas externos ao servidor?
Principais conclusões
Ferramenta desconhecida e mensagem malformada geram erros JSON-RPC; falha de execução retorna
isError: true.Erros de execução chegam ao modelo para que ele possa corrigir a solicitação.
Anotações orientam confirmações, mas não devem ser aceitas sem confiança no servidor.
Quiz da aula
6 perguntas · aprovação com 5 acertos · até 50 XP
Ao passar, você conclui a aula e mantém sua sequência. As perguntas erradas voltarão em sessões de revisão.
Pratique: crie um servidor MCP
Escreva código Python no editor e execute os testes com exemplos. O Python roda localmente no navegador usando WebAssembly.
Reporte cada falha no formato adequado
Leia o tipo da falha e a mensagem, separados por |. unknown_tool e malformed são erros de protocolo; invalid_input, api_failure e business_rule são erros de execução. Imprima o código JSON-RPC ou result isError=true, conforme o caso.
- Ferramenta desconhecida
- Data inválida
- Mensagem malformada
O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.
Dúvidas sobre esta lição
Travou em algum ponto? Pergunte. Descobriu algo? Compartilhe. Explicar também é uma ótima forma de aprender.
Carregando publicações…