get_organization_tree

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It openly reveals a critical known issue: the route returns 404 on the PRE Foundation backend and is kept only for future deployment. This is valuable honesty that saves the agent from pursuing a broken call. However, it does not disclose return structure, pagination, or other behavioral quirks, leaving some gaps.

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?

The description is two sentences: the first states the purpose clearly, the second documents a known issue. Every sentence earns its place, information is front-loaded, and there is no verbose padding. This is a model of concise, useful description.

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?

Given no output schema and no annotations, the description is reasonably complete for a simple read operation. It explains the purpose and warns about the current 404 issue. However, it does not describe the return format or expected hierarchy structure, and it fails to mention that get_organization_snapshot_as_of may be a working alternative. This leaves the agent with an incomplete picture of the tool's behavior and alternatives.

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?

The input schema provides 100% coverage with descriptions for all three parameters (dept_code, query_date, include_ineffective). The description adds no additional parameter meaning, meriting the baseline score of 3. The date-focused purpose aligns with the required query_date but does not explain syntax or interactions beyond the schema.

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?

The description clearly states a specific action: 'Get the organization hierarchy as of a specific date.' This is a distinct verb and resource, and the 'as of' phrasing indicates a temporal snapshot. It separates this tool from siblings like list_active_employees or export_departments, though it does not explicitly contrast with get_organization_snapshot_as_of, which may be a near duplicate.

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?

No guidance is given on when to use this tool versus alternatives. The known issue explains the tool is currently non-functional in the PRE Foundation environment, but it does not direct the agent to an alternative or state the intended use case beyond the purpose. The absence of when-to-use or when-not-to-use guidance other than the 404 warning leaves the agent without decision support among sibling tools.

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