notion_schema_intelligence

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

The description adds some behavioral context beyond the annotations: it reveals this is a dispatched domain-agent action executed under the caller's JWT, tenant, and company scope. However, with destructiveHint=true and readOnlyHint=false, the description should disclose what the action changes or destroys; it cannot, because the action's actual behavior is never described. No contradiction with the annotations.

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 tightly structured and front-loaded: a one-line action statement, a brief routing note, and a clean two-line argument list. Every sentence earns its place with no filler. The brevity reflects under-specification, which is penalized in other dimensions, but the structure itself is efficient and readable.

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?

Even though an output schema and annotations are present, the description omits the most critical information: what schema_intelligence actually does and when to select it. With over 20 notion-related siblings and a generic dispatch_domain_agent, an agent cannot correctly choose this tool. The routing and parameter hints fail to compensate for the absent semantic core.

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?

With 0% schema description coverage, the description carries the full burden and does provide basic semantics for both parameters: message is a 'Free-text objective' and inputs is an 'Optional JSON string of structured inputs.' This is meaningfully more than the bare schema offers, but it is shallow — what structured inputs schema_intelligence accepts is never specified.

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 opening sentence, 'Run the notion domain agent action `schema_intelligence`', essentially restates the tool's name without explaining what the action accomplishes. The routing details (domain-agent dispatcher, JWT/tenant/company scope) describe how it executes, not what schema intelligence does. Among 20+ notion_* siblings, there is no indication of the user objective this action serves.

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 its alternatives, notably the generic `dispatch_domain_agent` sibling or the many notion_* domain tools (notion_query_data, notion_search_intelligent, notion_plan_domain_intelligence). The 'message: Free-text objective' arg hint implies a natural-language goal is supplied, but nothing clarifies which goals map to schema_intelligence.

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