Tools — referência completa

As tools dividem-se em três modos (CONSULT / GUIDE / SETUP) com semântica diferente:

Determinísticas: dado o mesmo input, devolvem o mesmo output. Use para grounding citável (consult_security_requirements, get_guide_by_role, get_threat_landscape, prepare_sbd_toe_codegen_context).
Heurísticas / busca: ranking textual sobre o manual. Use para narrativa/conceito (search_sbd_toe_manual).

Cada tool abaixo lista parâmetros, output esperado, e padrão recomendado.

CONSULT mode

`search_sbd_toe_manual`

Pesquisa narrativa com citações — quando o utilizador faz perguntas conceptuais ("o que é threat modeling?", "como funciona SBOM").

Parâmetros: query (string)

Output: lista de excertos com chapter_id, section, score, text.

Quando preferir: perguntas abertas / explicativas. Quando NÃO usar: quando há filtros estruturados (risk_level, concern, role) — preferir consult_security_requirements.

`answer_sbd_toe_manual`

Q&A em linguagem natural — recupera contexto do manual e pede a síntese da resposta ao modelo do cliente via MCP sampling.

Parâmetros: question (string); topK, useVectorRecall, debug (opcionais)

Degradação honesta sem sampling

Em clientes sem suporte de MCP sampling (ex.: Claude Code), a tool não inventa uma síntese: devolve o retrieval formatado com a nota "MCP sampling not available… use search_sbd_toe_manual directly" e encaminha para search_sbd_toe_manual. Nesses clientes, preferir search_sbd_toe_manual desde o início.

`consult_security_requirements`

Determinístico. Devolve o conjunto de requisitos + controlos activos para um risk level, opcionalmente filtrado por concerns.

Parâmetros:

risk_level (L1 | L2 | L3) — obrigatório
concerns (string[]) — opcional, valores do enum fechado abaixo

Enum de concerns (fechado — 12 valores exatos): auth · logging · validation · api · config · integrity · distribution · ide · requirements · architecture · iac · encryption.

Valores fora deste enum não resolvem (não há fuzzy match): usar logging para monitorização, distribution para supply-chain / terceiros.

Output: (formatos de id reais — requisitos <CAT>-NNN, controlos CTRL-<domain>-<slug>-<hash>)

{
  "requirements": [{"requirement_id": "AUT-001", "name": "MFA obrigatório", "category": "AUT", "type": "base"}],
  "controls": [{
    "control_id": "CTRL-identity-gestao-de-identidades-acessos-e-ownership-d0919c69af",
    "name": "Gestão de identidades, acessos e ownership",
    "domain": "identity", "control_type": "preventive",
    "chapter_ids": ["08-iac-infraestrutura", "14-governanca-contratacao"],
    "_confidence": "direct"
  }],
  "active_domains": ["identity", "governance", "infrastructure"],
  "active_categories": ["ACC", "ARC", "AUT", "SES"],
  "rule_trace": [
    "REQUIREMENT_APPLIES_BY_RISK(risk_level=L2): 39 requirements active",
    "CONCERNS_FILTER_REQUIREMENTS(concerns=[auth])"
  ]
}

Tamanhos típicos: L1 ≈ 22k chars · L2 ≈ 36k chars · L3 ≈ 36k chars. Regra prática: sempre passar concerns em L2/L3 (reduz para ~9k por concern set).

Exemplo

consult_security_requirements({"risk_level": "L2", "concerns": ["auth", "logging"]})

Devolve apenas requisitos das categorias AUT/ACC/SES (auth) + LOG (logging), com rule_trace a confirmar CONCERNS_FILTER_REQUIREMENTS.

`map_sbd_toe_applicability`

Que capítulos / controlos se aplicam ao projecto dado o seu perfil.

Parâmetros: atributos do projecto (exposição, dados, stack, regulação aplicável).

Output: capítulos activos/condicionais/excluídos + rationale.

Quando preferir: decidir risk level ou perfilar um projecto novo.

`get_sbd_toe_chapter_brief`

Resumo estruturado de um capítulo — fases, artefactos (ART-*), tópicos.

Parâmetros: chapter_id (ex.: 06-desenvolvimento-seguro)

Output: phases, artifact_ids[], topics[], controls[].

`list_sbd_toe_chapters`

Índice — chapter_id, title, min_level, domains.

Parâmetros: risk_level (opcional — filtra)

`query_sbd_toe_entities`

Resolve uma entidade por id exato ou, se o token não for um id, faz fallback para busca semântica.

Parâmetros: query (string, obrigatório); entityType, chapterId, riskLevel, topK (opcionais)

Exemplo (id exato):

query_sbd_toe_entities({"query": "AUT-001"})

{
  "entities": [{
    "entity_type": "requirement", "requirement_id": "AUT-001",
    "category": "AUT", "name": "MFA obrigatório",
    "applicable_levels": {"L1": false, "L2": true, "L3": true},
    "source_bundle": "02-requisitos-seguranca"
  }],
  "total": 1, "match": "exact_id"
}

Erro de categoria comum

Um token como "CTRL-06" não é um id — não existe a forma CTRL-<capítulo>-<número>. Passá-lo não devolve "os controlos do capítulo 06"; cai em fallback semântico (match ≠ "exact_id"). Os ids reais são AUT-001, LOG-003 (requisitos), CTRL-<domain>-<slug>-<hash> (controlos), MT-NNN (ameaças), ART-… (artefactos). Para filtrar por tipo/domínio (em vez de resolver um id), usar resolve_entities.

`resolve_entities`

Filtro de baixo nível sobre a ontologia — dot-notation nos filters.

Parâmetros: record_type (control | requirement | role | practice), filters (objecto dot-path), limit (opcional)

Exemplos:

resolve_entities({"record_type": "role"})
// → lista os 13 roles canónicos

resolve_entities({"record_type": "control", "filters": {"domain": "architecture"}})
// → controlos do domínio architecture

GUIDE mode

`get_guide_by_role`

Determinístico. Práticas atribuídas por role e/ou fase do SDLC.

Parâmetros:

risk_level (L1 | L2 | L3) — obrigatório
role (string) — opcional
phase (string) — opcional (requirements | design | implement | test | deploy | operate | governance)

Output sem role/phase: role_summary{} + phase_summary{} (contagens) — útil para discovery. Output com role ou phase: assignments[] + user stories.

Regra crítica: sempre passar role ou phase para obter detalhes — sem nenhum dos dois, devolve só contagens.

`get_threat_landscape`

Determinístico. Threats relevantes para um risk level / concern, com mitigações.

Parâmetros:

risk_level (L1 | L2 | L3) — obrigatório
concerns (string[]) — opcional

Output: (ameaças MT-NNN; cada ligação cita o control_id real)

{
  "threats": [
    {
      "id": "MT-055", "name": "Interfaces expostas sem isolamento",
      "chapter_id": "04-arquitetura-segura", "threat_category": "STRIDE",
      "mitigation_confidence": "derived", "mitigation_strength": "parcial",
      "mitigated_by": [
        {"control_id": "CTRL-infrastructure-segmentacao-e-controlo-arquitetural-dceb3c1f0b", "domain": "infrastructure"}
      ]
    }
  ]
}

Importante:

mitigation_confidence: "derived" → ligação estrutural (chapter/bundle-match), fiável; mitigation_strength é tipicamente "parcial". (Não há valor "heuristic" nas ligações estruturais — se aparecer um fallback heurístico, rotular como inferido.)
A tool corre consult internamente — não chamar consult_security_requirements antes.

Limitação de routing conhecida (à data desta versão)

Os concerns de base (auth, validation, api, …) roteiam para o cap. 02 e devolvem as meta-ameaças de processo MT-021..038 (ausência/ambiguidade de requisitos), não as ameaças técnicas do domínio. Os concerns de domínio roteiam bem: architecture→cap. 04 (MT-055..072), iac→cap. 08, logging→cap. 12. Para ameaças técnicas de auth/validação, ancorar antes nos requisitos (consult_security_requirements) e cruzar. (Fix em curso no servidor — verificar o comportamento ao vivo.)

`plan_sbd_toe_repo_governance`

Lista os artefactos que o manual identifica para um repositório, agrupados por capítulo.

Output: lista de artifact_id + chapter_id + description.

Padrão: bootstrap de governança num repo novo — gerar a partir da lista artefactos por capítulo, criar os ficheiros vazios + READMEs.

`map_sbd_toe_review_scope`

Dado um conjunto de ficheiros alterados, devolve que bundles do manual rever.

Parâmetros: changed_files (string[])

Output: capítulos / bundles a rever + rationale (ex.: "ficheiros sob iac/ → cap. 08").

Padrão: PR auditor. Combinar com consult_security_requirements para enumerar controlos por capítulo.

`prepare_sbd_toe_codegen_context`

A tool mais sofisticada — devolve contexto determinístico para codegen, review ou test-plan.

Parâmetros:

task (string) — obrigatório
risk_level, mode (codegen | review | test-plan), stack, exposure, data_sensitivity, concerns, changed_files, regulatory_frameworks, include_regulatory_overlay — opcionais (passar tudo que se sabe)

Output (campo status):

`status`	Significado	Acção
`ready_for_codegen`	Scope claro, contexto pronto	Proceder — preencher `security_rationale`
`needs_clarification`	Inputs ambíguos	STOP — perguntar ao utilizador, não gerar código
`needs_decomposition`	Scope demasiado largo	STOP — propor 2–4 sub-tarefas
`unsupported_scope`	Capacidade ausente no servidor	STOP — reportar verbatim

Disciplina obrigatória após ready_for_codegen:

O citation_map devolvido é o mundo fechado de IDs válidos — não inventar IDs.
Preencher security_rationale.decisions[].cited_ids com pelo menos 1 ID por decisão não-trivial.
Preencher security_rationale.validations[] (validações concretas implementadas).
Preencher security_rationale.expected_evidence[] (artefactos para o reviewer — código sozinho não é evidência).
Preencher security_rationale.residual_risk (o que não foi endereçado).
Sinalizar completeness_report.m_recall < 1.0 ao utilizador (cobertura parcial).

Ver guia detalhado em Caso de uso — codegen grounded e no resource sbd://toe/grounded-codegen-guide.

SETUP mode

`generate_sbd_toe_skill`

Gera conteúdo de configuração para o cliente. Sem role devolve o agent guide canónico (sbd://toe/agent-guide); com role devolve uma skill ou subagent especializado no slice desse papel.

Parâmetros:

role (opcional) — uma das 13 personas canónicas (aliases resolvem; papel desconhecido → erro com a lista das 13).
format (skill | subagent) — skill = ficheiro de orientação (.claude/skills/…); subagent = definição de agente instalável (.claude/agents/…).
flavour (harnessed | skilled) — harnessed (default) embebe as tools mcp__sbd-toe__* (consulta o manual ao vivo); skilled embebe o slice congelado, sem tools live (offline).
risk_level (default L2), phase, include_detail, clientType — opcionais.

Output: content (markdown) + suggested_path + meta.coverage{chapters, of_total_chapters, assignments, user_stories, checklist_items} — a cobertura é declarada ("nothing silently truncated").

Resources paralelos: sbd://toe/skill/{role} e sbd://toe/subagent/{role} devolvem o mesmo conteúdo.

Ver Skills e agentes.

`setup_sbd_toe_agent` (prompt)

Tecnicamente um prompt, não uma tool — mas funciona como inicializador da sessão.

Parâmetros: riskLevel, projectRole

Output: capítulos activos + regras específicas.

Implementation view (V5)

Estas tools respondem a "como pôr de pé e governar o SbD" — distinta da vista operacional ("o que fazer em cada fase do SDLC"). Todas são coverage-preserving (paginação com coverage.hasMore/nextOffset; nada truncado em silêncio) e devolvem uma banda next com os próximos passos sugeridos.

`get_sbd_toe_chapter_implementation_checklist`

A narrativa de implementação canon/20 de um capítulo (o "como implementar"), distinta do DoD estruturado de user story (esse está em get_guide_by_role(include_detail=true)).

Parâmetros: chapter (id ou número), risk_level?, limit?, offset? Output: data.items[] (prosa com chunk_id rastreável) + next.

`get_sbd_toe_operating_model`

RACI, decision-rights, cadências de governança e modelos de organização, promovidos do rollout playbook.

Parâmetros: orgScope?, limit?, offset? Output: data.sections[] (prosa, paginado). Declara a fronteira: não prescreve organigrama (varia por setor/dimensão).

`plan_sbd_toe_rollout`

Roadmap por fases — as fases canónicas do ciclo de vida mapeadas a capítulos.

Parâmetros: orgProfile?, horizon?, limit?, offset? Output: data.phases[] (order, phase_id, label, chapter), model: "phase-ordered-mvp". O DAG de dependências é deferido (declarado, não fingido).

`get_sbd_toe_verification_matrix`

O lado EXPECTED da verificação: por requisito/controlo, o método de validação + evidência esperada + referência a EvidencePattern. Complemento determinístico do auditor e do plano de testes.

Parâmetros: risk_level (obrigatório), limit?, offset? Output: data.rows[] (evidence_pattern_id EP-*, requirement_id, control_id, validation_method, expected_evidence, evidence_type, expected_artifact_type_ids[], source) + coverage_gaps (requisitos sem padrão — declarados).

`assess_sbd_toe_implementation`

Auto-relato de postura: compara valores de KPI submetidos contra os thresholds por nível.

Parâmetros: kpi_values (mapa metric_id→número), risk_level Output: posture (below/at/above) + totals{applicable, meets, gaps, not_reported} + per_kpi + unknown_metrics. Stateless (nada é guardado); um KPI aplicável sem valor é not_reported, nunca pass.

Payload

Devolve os KPIs aplicáveis todos (sem paginação) — em L2 são ~92, o que torna o output grande. Submeter os kpi_values que se tem; os em falta vêm marcados not_reported.

`map_sbd_toe_regulatory_activation`

Lente regulatória (o inverso da provenance): dado um framework, que áreas/capítulos do manual ele activa.

Parâmetros: framework (DORA | NIS2 | CRA | RGPD; ou EXT-DORA…), limit?, offset? Output: data.activated[] por capítulo (mapping_count, obligation_count, by_target_type, example_citation) + totals. Framework desconhecido → erro -32602. Provenance declara: cross-check ≠ atestação de conformidade.

Diagnóstico

`inspect_sbd_toe_retrieval`

Diagnóstico do retriever — útil quando uma query devolve resultados inesperados. Mostra ranking, scores, e rule_trace completo.

Combinatória — padrões recomendados

Pergunta estruturada

consult_security_requirements(L2, ["auth"])

Pergunta narrativa

search_sbd_toe_manual("threat modeling stride")

Resposta complexa (threat model / security plan)

consult_security_requirements(L2, concerns)   # requisitos + controlos
get_threat_landscape(L2, concerns)             # threats relevantes
get_guide_by_role(L2, role)                    # práticas do role
→ gerar documento citando IDs dos 3 passos

PR review

map_sbd_toe_review_scope(changed_files)        # que capítulos
consult_security_requirements(risk_level, concerns)  # controlos activos
→ enumerar findings citando CTRL-* + chapter_id

Codegen grounded

prepare_sbd_toe_codegen_context(task, mode="codegen", ...)
ramificar por status (ver tabela acima)
se ready_for_codegen → gerar código + tests + security_rationale

A seguir

Resources e prompts — URIs sbd://toe/* para grounding estrutural e prompts pré-empacotados.

CONSULT mode​

search_sbd_toe_manual​

answer_sbd_toe_manual​

consult_security_requirements​

Exemplo​

map_sbd_toe_applicability​

get_sbd_toe_chapter_brief​

list_sbd_toe_chapters​

query_sbd_toe_entities​

resolve_entities​

GUIDE mode​

get_guide_by_role​

get_threat_landscape​

plan_sbd_toe_repo_governance​

map_sbd_toe_review_scope​

prepare_sbd_toe_codegen_context​

SETUP mode​

generate_sbd_toe_skill​

setup_sbd_toe_agent (prompt)​

Implementation view (V5)​

get_sbd_toe_chapter_implementation_checklist​

get_sbd_toe_operating_model​

plan_sbd_toe_rollout​

get_sbd_toe_verification_matrix​

assess_sbd_toe_implementation​

map_sbd_toe_regulatory_activation​

Diagnóstico​

inspect_sbd_toe_retrieval​

Combinatória — padrões recomendados​

Pergunta estruturada​

Pergunta narrativa​

Resposta complexa (threat model / security plan)​

PR review​

Codegen grounded​

A seguir​

CONSULT mode

`search_sbd_toe_manual`

`answer_sbd_toe_manual`

`consult_security_requirements`

Exemplo

`map_sbd_toe_applicability`

`get_sbd_toe_chapter_brief`

`list_sbd_toe_chapters`

`query_sbd_toe_entities`

`resolve_entities`

GUIDE mode

`get_guide_by_role`

`get_threat_landscape`

`plan_sbd_toe_repo_governance`

`map_sbd_toe_review_scope`

`prepare_sbd_toe_codegen_context`

SETUP mode

`generate_sbd_toe_skill`

`setup_sbd_toe_agent` (prompt)

Implementation view (V5)

`get_sbd_toe_chapter_implementation_checklist`

`get_sbd_toe_operating_model`

`plan_sbd_toe_rollout`

`get_sbd_toe_verification_matrix`

`assess_sbd_toe_implementation`

`map_sbd_toe_regulatory_activation`

Diagnóstico

`inspect_sbd_toe_retrieval`

Combinatória — padrões recomendados

Pergunta estruturada

Pergunta narrativa

Resposta complexa (threat model / security plan)

PR review

Codegen grounded

A seguir