notion_personal_ask

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

Adds substantial behavior beyond the annotations: long answers are not repeated in tool output, full content is written to answer_path/code_artifacts and must be read from file, external responses are data not instructions, and timeouts must not trigger a resubmit. The retry/idempotency semantics overlap somewhat with idempotentHint=false but add the specific failure-mode rule. No auth or rate-limit detail.

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?

Front-loads the core action, then packs constraints into short declarative fragments with no filler. The telegraphic style ("Personal chat only; never Custom Agent.") is dense but readable. Slightly list-like rather than prose, but every sentence carries an operational rule.

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?

For an open-world, non-idempotent tool with no output schema, the description covers the critical gaps: where the real answer lives (local file), why output looks truncated, and the correct recovery path when a timeout occurs. Authentication, quota, and the prompt vs prompt_file choice remain unaddressed, but the operationally decisive information is present.

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?

Schema description coverage is 50%. The description clarifies request_key's intended reuse semantics ("Reuse it after errors; do not invent a new key to retry"), reinforcing the schema. However, it says nothing about prompt vs prompt_file selection or timeout_seconds, leaving half the parameters unexplained outside 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?

States a specific verb+resource ("Create a personal chat") and adds a scope constraint ("Personal chat only; never Custom Agent"), which helps distinguish it from notion_personal_submit/reply. The "and wait" phrasing is a bit loose but conveys the synchronous nature. It does not explicitly name the siblings it competes with, so it stops short of a 5.

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?

Gives explicit routing guidance: prefer "submit plus read" for reliable recovery, or supply request_key, and warns that a timeout is not grounds to resubmit. That is concrete when/when-not guidance. It still doesn't say when a plain synchronous ask is preferred over notion_personal_submit in the first place, so not fully exhaustive.

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