Senado BR — Brazilian Federal Senate Open Data

Estrutura organizacional

senado_estrutura_organizacional

Read-onlyIdempotent

Retrieves the Brazilian Federal Senate organizational hierarchy for a given unit, listing superior path and all subordinate units with acronyms, names, and levels.

Instructions

Estrutura organizacional (organograma) do Senado Federal até o nível de serviço. Dada uma unidade (sigla como 'DGER' ou nome como 'Diretoria-Geral'), retorna { unidade, caminho[], totalSubordinadas, subordinadas[] }: caminho são os órgãos superiores (da cúpula até o superior imediato) e subordinadas são TODAS as unidades da subárvore (secretarias, coordenações, serviços e núcleos), cada uma com sigla, nome e nivel (profundidade relativa). Use para responder 'o que está sob a DGER', 'quais secretarias/serviços pertencem a X' ou para entender a hierarquia administrativa. Para CONTAR ou LISTAR servidores sob uma unidade, use senado_servidores com subordinadasA. Fonte: portal institucional (a API de dados abertos não publica a árvore completa).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limite`	No	Máximo de subordinadas listadas (padrão: 200)
`unidade`	Yes	Sigla (ex.: 'DGER', 'SEGRAF') ou nome (ex.: 'Diretoria-Geral') da unidade

Output Schema

TableJSON Schema

Name	Required	Description	Default
`provenance`	Yes
`attribution`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv3.18.4Oct 14, 2026

changedOutput schema / properties / provenance / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "citation": {
-        "type": "string"
-      },
-      "data_vintage": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "field_sources": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "data_vintage": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "dataset_id": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "fields": {
-              "items": {
-                "type": "string"
-              },
-              "minItems": 1,
-              "type": "array"
-            },
-            "retrieved_at": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "served_from_cache": {
-              "type": [
-                "boolean",
-                "null"
-              ]
-            },
-            "source_url": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "fields",
-            "source_url",
-            "dataset_id",
-            "data_vintage",
-            "retrieved_at"
-          ],
-          "type": "object"
-        },
-        "minItems": 1,
-        "type": "array"
-      },
-      "license": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "retrieval": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "anomalies": {
-                "items": {
-                  "additionalProperties": false,
-                  "properties": {
-                    "count": {
-                      "maximum": 9007199254740991,
-                      "minimum": 1,
-                      "type": "integer"
-                    },
-                    "kind": {
-                      "enum": [
-                        "timeout",
-                        "network",
-                        "http_4xx",
-                        "http_5xx",
-                        "rate_limited",
-                        "malformed_body"
-                      ],
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "kind",
-                    "count"
-                  ],
-                  "type": "object"
-                },
-                "type": "array"
-              },
-              "attempts": {
-                "maximum": 9007199254740991,
-                "minimum": 1,
-                "type": "integer"
-              },
-              "requests": {
-                "maximum": 9007199254740991,
-                "minimum": 1,
-                "type": "integer"
-              },
-              "unstable": {
-                "type": "boolean"
-              }
-            },
-            "required": [
-              "requests",
-              "attempts",
-              "anomalies",
-              "unstable"
-            ],
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "retrieved_at": {
-        "type": "string"
-      },
-      "source": {
-        "type": "string"
-      },
-      "source_url": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "source",
-      "source_url",
-      "data_vintage",
-      "retrieved_at",
-      "retrieval",
-      "citation",
-      "license"
-    ],
-    "type": "object"
-  },
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "citation": {
-          "type": "string"
-        },
-        "data_vintage": {
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "field_sources": {
-          "items": {
-            "additionalProperties": false,
-            "properties": {
-              "data_vintage": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "dataset_id": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "fields": {
-                "items": {
-                  "type": "string"
-                },
-                "minItems": 1,
-                "type": "array"
-              },
-              "retrieved_at": {
-                "type": [
-                  "string",
-                  "null"
-                ]
-              },
-              "served_from_cache": {
-                "type": [
-                  "boolean",
-                  "null"
-                ]
-              },
-              "source_url": {
-                "type": "string"
-              }
-            },
-            "required": [
-              "fields",
-              "source_url",
-              "dataset_id",
-              "data_vintage",
-              "retrieved_at"
-            ],
-            "type": "object"
-          },
-          "minItems": 1,
-          "type": "array"
-        },
-        "license": {
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "retrieval": {
-          "anyOf": [
-            {
-              "additionalProperties": false,
-              "properties": {
-                "anomalies": {
-                  "items": {
-                    "additionalProperties": false,
-                    "properties": {
-                      "count": {
-                        "maximum": 9007199254740991,
-                        "minimum": 1,
-                        "type": "integer"
-                      },
-                      "kind": {
-                        "enum": [
-                          "timeout",
-                          "network",
-                          "http_4xx",
-                          "http_5xx",
-                          "rate_limited",
-                          "malformed_body"
-                        ],
-                        "type": "string"
-                      }
-                    },
-                    "required": [
-                      "kind",
-                      "count"
-                    ],
-                    "type": "object"
-                  },
-                  "type": "array"
-                },
-                "attempts": {
-                  "maximum": 9007199254740991,
-                  "minimum": 1,
-                  "type": "integer"
-                },
-                "requests": {
-                  "maximum": 9007199254740991,
-                  "minimum": 1,
-                  "type": "integer"
-                },
-                "unstable": {
-                  "type": "boolean"
-                }
-              },
-              "required": [
-                "requests",
-                "attempts",
-                "anomalies",
-                "unstable"
-              ],
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "retrieved_at": {
-          "type": "string"
-        },
-        "source": {
-          "type": "string"
-        },
-        "source_url": {
-          "type": "string"
-        }
-      },
-      "required": [
-        "source",
-        "source_url",
-        "data_vintage",
-        "retrieved_at",
-        "retrieval",
-        "citation",
-        "license"
-      ],
-      "type": "object"
-    },
-    "minItems": 1,
-    "type": "array"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "citation": {
+        "type": "string"
+      },
+      "data_vintage": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "derivation_note": {
+        "type": "string"
+      },
+      "derived": {
+        "type": "boolean"
+      },
+      "field_sources": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "data_vintage": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "dataset_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "fields": {
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "type": "array"
+            },
+            "retrieved_at": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "served_from_cache": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "source_url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "fields",
+            "source_url",
+            "dataset_id",
+            "data_vintage",
+            "retrieved_at"
+          ],
+          "type": "object"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "license": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "notices": {
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "retrieval": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "anomalies": {
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "count": {
+                      "maximum": 9007199254740991,
+                      "minimum": 1,
+                      "type": "integer"
+                    },
+                    "kind": {
+                      "enum": [
+                        "timeout",
+                        "network",
+                        "http_4xx",
+                        "http_5xx",
+                        "rate_limited",
+                        "malformed_body"
+                      ],
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "kind",
+                    "count"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "attempts": {
+                "maximum": 9007199254740991,
+                "minimum": 1,
+                "type": "integer"
+              },
+              "requests": {
+                "maximum": 9007199254740991,
+                "minimum": 1,
+                "type": "integer"
+              },
+              "unstable": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "requests",
+              "attempts",
+              "anomalies",
+              "unstable"
+            ],
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "retrieved_at": {
+        "type": "string"
+      },
+      "revision": {
+        "additionalProperties": false,
+        "properties": {
+          "note": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status": {
+            "enum": [
+              "current",
+              "provisional",
+              "final"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "status",
+          "note"
+        ],
+        "type": "object"
+      },
+      "source": {
+        "type": "string"
+      },
+      "source_url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "source",
+      "source_url",
+      "data_vintage",
+      "retrieved_at",
+      "retrieval",
+      "citation",
+      "license"
+    ],
+    "type": "object"
+  },
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "citation": {
+          "type": "string"
+        },
+        "data_vintage": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "derivation_note": {
+          "type": "string"
+        },
+        "derived": {
+          "type": "boolean"
+        },
+        "field_sources": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "data_vintage": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "dataset_id": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "fields": {
+                "items": {
+                  "type": "string"
+                },
+                "minItems": 1,
+                "type": "array"
+              },
+              "retrieved_at": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "served_from_cache": {
+                "type": [
+                  "boolean",
+                  "null"
+                ]
+              },
+              "source_url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "fields",
+              "source_url",
+              "dataset_id",
+              "data_vintage",
+              "retrieved_at"
+            ],
+            "type": "object"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "license": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "notices": {
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "retrieval": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "anomalies": {
+                  "items": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "count": {
+                        "maximum": 9007199254740991,
+                        "minimum": 1,
+                        "type": "integer"
+                      },
+                      "kind": {
+                        "enum": [
+                          "timeout",
+                          "network",
+                          "http_4xx",
+                          "http_5xx",
+                          "rate_limited",
+                          "malformed_body"
+                        ],
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "count"
+                    ],
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "attempts": {
+                  "maximum": 9007199254740991,
+                  "minimum": 1,
+                  "type": "integer"
+                },
+                "requests": {
+                  "maximum": 9007199254740991,
+                  "minimum": 1,
+                  "type": "integer"
+                },
+                "unstable": {
+                  "type": "boolean"
+                }
+              },
+              "required": [
+                "requests",
+                "attempts",
+                "anomalies",
+                "unstable"
+              ],
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "retrieved_at": {
+          "type": "string"
+        },
+        "revision": {
+          "additionalProperties": false,
+          "properties": {
+            "note": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "status": {
+              "enum": [
+                "current",
+                "provisional",
+                "final"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "status",
+            "note"
+          ],
+          "type": "object"
+        },
+        "source": {
+          "type": "string"
+        },
+        "source_url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "source",
+        "source_url",
+        "data_vintage",
+        "retrieved_at",
+        "retrieval",
+        "citation",
+        "license"
+      ],
+      "type": "object"
+    },
+    "minItems": 1,
+    "type": "array"
+  }
+]

Changed3 schema fields changedv3.15.2Oct 7, 2026

addedOutput schema / properties / attribution

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / provenance

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "citation": {
+          "type": "string"
+        },
+        "data_vintage": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "field_sources": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "data_vintage": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "dataset_id": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "fields": {
+                "items": {
+                  "type": "string"
+                },
+                "minItems": 1,
+                "type": "array"
+              },
+              "retrieved_at": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "served_from_cache": {
+                "type": [
+                  "boolean",
+                  "null"
+                ]
+              },
+              "source_url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "fields",
+              "source_url",
+              "dataset_id",
+              "data_vintage",
+              "retrieved_at"
+            ],
+            "type": "object"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "license": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "retrieval": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "anomalies": {
+                  "items": {
+                    "additionalProperties": false,
+                    "properties": {
+                      "count": {
+                        "maximum": 9007199254740991,
+                        "minimum": 1,
+                        "type": "integer"
+                      },
+                      "kind": {
+                        "enum": [
+                          "timeout",
+                          "network",
+                          "http_4xx",
+                          "http_5xx",
+                          "rate_limited",
+                          "malformed_body"
+                        ],
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "count"
+                    ],
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "attempts": {
+                  "maximum": 9007199254740991,
+                  "minimum": 1,
+                  "type": "integer"
+                },
+                "requests": {
+                  "maximum": 9007199254740991,
+                  "minimum": 1,
+                  "type": "integer"
+                },
+                "unstable": {
+                  "type": "boolean"
+                }
+              },
+              "required": [
+                "requests",
+                "attempts",
+                "anomalies",
+                "unstable"
+              ],
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "retrieved_at": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "source_url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "source",
+        "source_url",
+        "data_vintage",
+        "retrieved_at",
+        "retrieval",
+        "citation",
+        "license"
+      ],
+      "type": "object"
+    },
+    {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "citation": {
+            "type": "string"
+          },
+          "data_vintage": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "field_sources": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "data_vintage": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "dataset_id": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "fields": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "minItems": 1,
+                  "type": "array"
+                },
+                "retrieved_at": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "served_from_cache": {
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "source_url": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "fields",
+                "source_url",
+                "dataset_id",
+                "data_vintage",
+                "retrieved_at"
+              ],
+              "type": "object"
+            },
+            "minItems": 1,
+            "type": "array"
+          },
+          "license": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "retrieval": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "anomalies": {
+                    "items": {
+                      "additionalProperties": false,
+                      "properties": {
+                        "count": {
+                          "maximum": 9007199254740991,
+                          "minimum": 1,
+                          "type": "integer"
+                        },
+                        "kind": {
+                          "enum": [
+                            "timeout",
+                            "network",
+                            "http_4xx",
+                            "http_5xx",
+                            "rate_limited",
+                            "malformed_body"
+                          ],
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "kind",
+                        "count"
+                      ],
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  "attempts": {
+                    "maximum": 9007199254740991,
+                    "minimum": 1,
+                    "type": "integer"
+                  },
+                  "requests": {
+                    "maximum": 9007199254740991,
+                    "minimum": 1,
+                    "type": "integer"
+                  },
+                  "unstable": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "requests",
+                  "attempts",
+                  "anomalies",
+                  "unstable"
+                ],
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "retrieved_at": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "source_url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "source",
+          "source_url",
+          "data_vintage",
+          "retrieved_at",
+          "retrieval",
+          "citation",
+          "license"
+        ],
+        "type": "object"
+      },
+      "minItems": 1,
+      "type": "array"
+    }
+  ]
+}

addedOutput schema / required

Added value: +[
+  "provenance",
+  "attribution"
+]

Addedv3.9.0Sep 24, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety and idempotency are covered. The description adds valuable behavioral context: it explains the return shape (caminho, totalSubordinadas, subordinadas with sigla, nome, nivel), the source (portal institucional, not the open-data API), and the limitation that it goes only to service level. It does not, however, disclose rate limits or pagination behavior beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph with clear structure: purpose first, then return-shape details, then usage examples, then alternative, then source note. It is front-loaded and efficient, though slightly long for the information delivered because the return shape might be partially covered by the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists, the description does not need to explain return values exhaustively, but it still provides a concise contract for the response (caminho, subordinadas, etc.). It also closes the loop on the known limitation of the data source, which is crucial for an agent to avoid expecting open-data coverage. Nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters, including examples for 'unidade' and the limite default/max. The description repeats the sigla/name examples but adds no new parameter syntax or constraints beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it delivers the organizational structure (organograma) of the Federal Senate down to service level, given a unit. It clearly distinguishes itself from sibling tools by naming senado_servidores as the alternative for counting/listing staff.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly describes when to use the tool ('o que está sob a DGER', 'quais secretarias/serviços pertencem a X') and gives an exclusion: for counting or listing servants, use senado_servidores with subordinadasA. This is precise routing guidance.

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

Deploy Server