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

注解已经声明readOnlyHint=true、idempotentHint=true和destructiveHint=false,表明这是一个安全的读操作。描述'Get details'没有添加超出注解的行为上下文,如认证要求、错误条件或返回格式。因此没有为agent提供超越已有结构的额外行为信息。

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?

描述是一个简洁的单句'Get details of a specific webhook.',每个词都有作用,没有冗余。对于这样一个简单的读操作,这个长度是合适的,且关键信息'get'和'specific'放在前面,结构清晰。

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?

工具简单,有2个参数,注解涵盖了安全特性。但描述没有说明返回值的内容,且没有输出schema来补偿。对于agent来说,调用方式清晰,但返回格式和错误情况不明,略有缺口。

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对两个参数(api_key和webhook_id)都有描述,覆盖率100%。描述本身没有添加任何参数语义,没有解释ID格式或API密钥的传递方式。根据覆盖率高的基线,评分为3。

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?

描述使用明确的动词'Get'和资源'details of a specific webhook',清楚表明这是获取单个webhook详细信息的操作。'specific'一词将其与兄弟工具list_webhooks区分开来,后者用于列出所有webhook。标题'Get Webhook Details'也与此一致,无歧义。

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?

描述没有明确说明何时使用此工具或何时使用替代方案。'specific webhook'隐含了需要webhook_id的使用场景,但没有提供与list_webhooks或update_webhook等兄弟工具的选择指导。没有排除条件或替代方案提示,因此用法只能推断。

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