YouSpot

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

Goes well beyond the destructiveHint=true annotation: it describes the two outcomes (no sign-in → added immediately, tools ready; sign-in → returns `sign_in_url`), instructs the agent not to claim connection before browser completion, and covers the already-added case returning the connector's page. This is rich state-transition disclosure.

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?

Four sentences, front-loaded with purpose followed by behavioral cases. Dense but every sentence carries a distinct outcome (no-sign-in, sign-in, already-added); minor tightening possible but no filler.

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 a single-parameter mutation tool with no output schema, the description covers the critical flows an agent must handle: immediate add, deferred sign-in with URL handoff, and idempotent already-added behavior. Nothing essential to correct invocation is missing.

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 coverage is 100%, so the `name` parameter is already documented including the 'as list_connectors reported it' example. The description restates 'by its name' without adding format or matching rules beyond the schema, so the baseline 3 applies.

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 ('Start connecting') and resource ('one connector from list_connectors'), and anchors the resource to the sibling that enumerates it. An agent can distinguish it from list_connectors or disconnect_integration without opening a schema.

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 an explicit gating condition: 'Call it only when the user asked to connect that service.' It also implicitly routes discovery to list_connectors ('from list_connectors, by its name'). Both when-to-use and the alternative discovery path are spelled out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds only the emoji naming convention; it says nothing about channel membership requirements, whether reactions can be removed, or rate limiting, so it provides modest extra context.

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?

One tight sentence, front-loaded with the verb and including a concrete example inline. Nothing extraneous and nothing buried.

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 a simple action tool with no output schema and full annotation coverage, this is close but leaves real gaps: the required 'ts' parameter's format is unexplained and 'team_id' is entirely undocumented. An agent could still call it, but might guess wrong on the timestamp.

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 coverage is 50%: emoji and ts are described (the description usefully reinforces emoji with examples like 'eyes'), but channel_id and team_id have no description at all. Critically, 'ts' is only glossed as "The message's ts" and the description does not clarify the Slack timestamp format, so the coverage gap is not compensated.

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?

A specific verb ('Add') plus resource ('emoji reaction to a Slack message') makes the operation unmistakable and naturally distinct from siblings like send_slack_message or draft_slack_message. It stops short of explicitly contrasting itself with any sibling, so it lands just below the top mark.

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?

There is no guidance on when to use this versus send_slack_message/draft_slack_message, or on prerequisites (must the bot be in the channel? must the message exist?). The agent must infer all of that from the tool name alone.

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

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

readOnlyHint=true already covers the safety profile, but the description goes further by enumerating the three return states ('running', 'replied' with reply text, 'failed'), which is the key behavioral fact for a polling tool with no output schema. It doesn't cover edge cases like an unknown/expired trace_id or eventual expiry of the reply.

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?

Three tight sentences with the core action front-loaded, then return states, then polling cadence. No filler or redundancy.

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 a one-parameter read/poll tool with annotations covering safety and no output schema, the description supplies the missing return-state semantics and polling guidance an agent needs. Only minor gaps remain (behavior on invalid trace_id, whether replies persist).

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 coverage is 100% and the single parameter's description already states it is 'The trace_id message_agent returned.' The description repeats that origin but adds no format, length, or validity detail beyond the schema, so baseline 3 applies.

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 (read) and resource (an agent's reply), and ties it directly to the sibling that produces the input: 'Read what an agent answered to a message_agent call.' An agent can distinguish this from message_agent and other read tools without opening the schema.

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?

Clearly establishes the usage context (call it after message_agent, using the trace_id that call returned) and gives explicit cadence guidance ('Wait at least a minute between checks'). It stops short of stating when NOT to use it or what to do on repeated 'running'/'failed' states, so no full when-not/alternatives coverage.

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

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

Annotations only supply readOnlyHint=true, so the description carries most of the burden and does so richly: it explains the top_engagers ranking rule (commenters/reactors by follower count, unfetched profiles omitted) and enumerates every engagement_sync outcome ('off', 'blocked', 'outside_window', 'pending', 'no_engagement_yet') with the required behavior for each. This is behavior an agent could not infer from the schema or 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?

Front-loads the purpose and usage triggers before the mechanics, and the dense engagement_sync enumeration is information the agent actually needs to respond correctly. It is long and could be tightened, but almost every sentence carries operational content rather than padding.

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?

With no output schema, the description takes on the job of explaining return contents (per-post stats, comment samples, engager headlines, top_engagers) and the analysis angles to cover. It also handles the degraded-data paths, so an agent can both call it and interpret the result without guessing.

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 coverage is 100%, so baseline is 3, but the description adds genuine meaning: activity_id must come from a linkedin_post object's json_data, and passing it narrows the analysis to one post. post_count's default/max is only in the schema, but overall the description enriches the parameters.

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 (analyze) plus resource (the user's most recent LinkedIn posts) and enumerates what the payload contains: per-post stats, a sample of comments with authors, and engager headlines. This is enough to distinguish it from siblings like get_my_linkedin_posts or linkedin_analytics, which return raw posts or metrics rather than a commentary/audience analysis.

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 triggering phrases ('analysis of their recent posts', 'what people are saying about them', 'who their audience is') and a scoping condition for the single-post mode via activity_id. It does not name a competing sibling to route away from, so it falls just short of the 5 bar.

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

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

With annotations already declaring readOnlyHint=false and destructiveHint=true, the description adds important context beyond those flags: the message leaves the inbox but remains in All Mail and is fully recoverable. This corrects a potentially alarming destructive impression and supplies the confirmation rule, though it does not cover edge cases like already-archived messages or error behavior.

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?

Two tightly written sentences with the core effect front-loaded, followed by the usage constraint. Every sentence earns its place and there is no redundancy.

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 a simple two-parameter mutation tool with full schema coverage and annotations, the description covers purpose, reversibility, and confirmation guidance well. Minor gaps around error handling and already-archived behavior are acceptable given the tool's low complexity.

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 100%, and the schema already documents both account and message_id including the omit-to-try-all-mailboxes behavior. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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 states a specific verb (archive) and resource (one Gmail message), and distinguishes itself from the sibling archive_outlook_message by naming Gmail explicitly. It also clarifies the immediate effect, so an agent can identify the operation without opening the schema.

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?

It gives explicit usage guidance: use only when the user asked for archiving, and confirm first if it is the agent's own suggestion. It does not name alternative tools such as search_gmail_messages or get_gmail_message, so it falls short of full when/when-not/alternatives coverage.

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

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

The annotations already mark this as a non-read-only, destructive operation, so the safety profile is known. The description adds important behavioral context that archiving is recoverable and operates on a single message, though it does not discuss auth, rate limits, or multi-mailbox behavior.

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 concise sentences with no wasted text. The core action is front-loaded, followed by the confirmation policy.

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 a simple mutation tool with full parameter descriptions and annotations, the description covers the essential points: what it does, where the message goes, recoverability, and confirmation policy. No output schema exists, so return values need not be explained.

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 100%, so both parameters are documented in the schema. The description reinforces that only one message is affected but does not add meaning beyond the schema for account or message_id.

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 gives a specific verb and resource: "Move one Outlook message to the Archive folder." It also states the effect, "leaves the inbox and stays recoverable," which clearly distinguishes archiving from deleting or marking. An agent can identify the operation without opening the schema.

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?

The description provides explicit usage constraints: "Use only when the user asked for it; confirm first if it is your own suggestion." This tells the agent both when to invoke the tool and when extra confirmation is required.

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

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

Annotations already provide readOnlyHint=true, and the description adds meaningful behavior beyond that: it is answered by generating a read-only SQL query, returns columns and rows rather than prose, and has a 500-character input limit. This is useful operational context not present in the schema or 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?

Four sentences, each carrying distinct information: scope and examples, execution/output behavior, routing to an alternative, and an input limit. The examples replace lengthy prose and make the description efficient without being bloated.

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 a one-string-parameter tool with a readOnly annotation and no output schema, the description covers what to ask, when to use it instead of search_connections, what kind of result to expect (columns and rows), and the input length limit. No critical information for correct invocation is missing.

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 100%, so the baseline is 3; the description adds value by giving concrete example questions and the under-500-characters constraint. This meaningfully helps the agent craft a valid free-form question beyond the schema's brief 'plain English' note.

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 'Ask a free-form question about the user's LinkedIn connections' and enumerates the exact query categories it covers with concrete examples: aggregates, rankings, date ranges, location filters, and combined conditions. The phrase 'that the other tools can't express' and the explicit contrast with search_connections clearly distinguish it from siblings.

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?

Explicitly routes simple lookups away from this tool: 'Prefer search_connections for a simple name/company/title lookup — it is faster.' It also defines the usage space positively with categories and multi-condition examples, giving the agent a clear decision rule.

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

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

The annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: it generates a read-only SQL query, returns columns/rows instead of prose, instructs summarizing rows with a count, and advises triggering a sync if no companies are found. This goes well beyond the structured annotation.

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 well-organized: clear purpose first, then examples, then behavioral guidance, then a practical edge case. Every sentence contributes useful information without redundancy or fluff.

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 the tool has only one parameter and no output schema, the description covers all necessary operational details: what it queries, how results are returned, how to present them, and what to do when no data is synced. Nothing critical is missing.

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 schema already documents the 'question' parameter fully, so the baseline is 3. The description adds extra value by specifying the 500-character limit and instructing to pass the user's own phrasing, which helps the agent invoke the tool correctly.

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 uses a specific verb ('Query') and clearly identifies the resource ('the user's HubSpot companies'). It explicitly distinguishes this tool from the sibling ask_about_hubspot_contacts by focusing on synced company data and gives concrete examples of supported question types.

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?

It explicitly says 'Use this for any question about their CRM companies' and lists question categories, which provides a clear usage context. However, it does not name any alternative tools or state when not to use this tool, so the guidance is clear but lacks explicit exclusions.

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

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

The description reveals key behavior beyond the readOnlyHint annotation: it generates a read-only SQL query, returns columns and rows rather than prose, and tells the agent to summarize rows and report the count. It also specifies the fallback behavior when no contacts are synced (direct to /hubspot/import). This is substantial behavioral context that annotations alone do not provide.

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 detailed but every sentence serves a distinct purpose: defining the resource, illustrating use cases, explaining the output behavior, and giving a fallback instruction. The key information is front-loaded, and there is no filler or repetition.

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 the tool has one parameter, no output schema, and a clear read-only annotation, the description supplies all needed context: what the tool does, what kinds of questions to ask, what the response format looks like, and what to do in the edge case of no synced contacts. Nothing critical is missing.

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 already covers the single 'question' parameter well, including 'plain English' and preserving user phrasing. The description adds the 500-character limit and a rich set of example questions, which clarifies what kinds of queries are appropriate. This goes slightly beyond the schema's baseline but does not radically expand it.

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 opens with a specific verb ('Query') and resource ('the user's HubSpot contacts'), and clarifies these are people synced from connected HubSpot portals. It distinguishes itself from sibling tools like ask_about_hubspot_companies by focusing on contacts rather than companies. The scope is immediately clear and actionable.

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?

The description explicitly states 'Use this for any question about their CRM contacts' and provides a broad set of example query categories. However, it does not explicitly mention when not to use it or name alternatives like ask_about_hubspot_companies, so it stops short of full when/when-not guidance.

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

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

The description adds valuable behavioral detail beyond the readOnlyHint annotation: acceptance is inferred via connection appearance, the export covers only recent/pending invitations rather than lifetime history, the tool returns columns and rows, and questions must be under 500 characters. These are important operational nuances an agent needs to set expectations and interpret results.

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 compact and every sentence earns its place: purpose, uniqueness, examples, inference note, data limitation, output shape, and input constraint. It is front-loaded with the core purpose and uses examples efficiently.

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 a single-parameter tool with no output schema, the description is fully self-sufficient. It explains what the tool does, how to use it, what behavioral caveats apply, what kind of output to expect, and the input constraint. Nothing essential is missing.

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 schema already documents the single 'question' parameter with 100% coverage, so the baseline is 3. The description adds meaningful extra semantics: the question must be about invitations, should be phrased in plain English, and must stay under 500 characters. This goes beyond the schema and helps the agent formulate valid inputs.

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 the tool's purpose: asking questions about the user's LinkedIn invitations, specifically requests sent and received. It also distinguishes itself by stating 'This is the only tool that can see invitations,' which separates it from siblings like ask_about_connections.

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?

The description gives explicit example questions and states when the tool should be used ('Use it for questions like...'). It doesn't explicitly name alternatives or spell out when not to use it, but the 'only tool that can see invitations' statement makes the usage context strong and clear.

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

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

Annotation already covers readOnlyHint=true, so 'Reads only' is redundant. The description earns credit by disclosing what the audit actually inspects (log noise, unnamed entity mentions, duplicated records) and by imposing a presentation constraint on the agent. With no output schema, it still leaves the 'card' format undefined.

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 opening sentence is an unstructured run-on that strings five distinct finding types together with no separators, making it harder to scan than a bulleted enumeration would be. The two trailing imperatives are tight and front-loaded at the end. Roughly the right length, poor internal structure.

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?

With zero parameters, no output schema, and a readOnly annotation, the main risk is ambiguity about what comes back — and the description compensates by enumerating the finding categories. The reference to 'the card it names' is the one loose end, since no card type is specified.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is fully covered. Baseline 4 applies; no additional meaning is needed or given.

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 names a specific diagnostic resource and enumerates the finding categories it produces: object counts per type, machine-log noise, dangling named entities, duplicate records, and re-saved documents. An agent can tell this is a graph-cleanliness audit rather than a generic search or list. It never names a sibling, so differentiation from list_duplicate_suggestions or what_needs_attention is left to inference.

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?

It gives one concrete workflow instruction ('let the reader decide group by group; never write the findings out as a table yourself'), which shapes how output is handled. It does not say when this audit is preferable to sibling diagnostics like list_duplicate_suggestions, similar_objects, or what_needs_attention. Usage is implied rather than routed.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description adds the meaningful behavioral constraint that only unsent texts can be cancelled. It does not say what error or state results if the text was already sent or the id is stale, which keeps it out of 5 territory.

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?

Two short sentences, front-loaded with the action and its precondition, followed by the id source. Nothing is redundant and nothing is missing that belongs here.

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 a single-parameter cancellation tool with no output schema and annotations covering destructiveness, the description covers what it does, the precondition, and where the id comes from. Only the failure mode (already-sent or unknown task_id) is left unaddressed.

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 coverage is 100% and the schema itself only says 'the scheduled text to cancel'. The description goes beyond that by telling the agent where to obtain task_id (scheduling response or list_scheduled_texts), which is genuine added semantics rather than restatement.

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 (Cancel) and resource (scheduled text), plus the provenance constraint that the text must have been created by send_text_to_user and not yet sent. This clearly separates it from list_scheduled_texts, which it instead points to as a source of the id.

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 a clear condition for use (the text is scheduled and unsent, so its task_id must come from the scheduling response or list_scheduled_texts). It stops short of explicitly stating what to do when the message has already gone out, but the precondition implicitly excludes that case.

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

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

Goes well beyond the annotations by disclosing the stateful baseline behavior ('the first call records a baseline and reports no change, which is normal') and per-page/per-tag snapshot isolation. It never claims read-only, so the destructiveHint=true annotation is not contradicted, but it also does not explain what that hint refers to (persisting/replacing a stored snapshot), which is the one behavioral fact left uncovered.

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-loaded with the core action and result, then use cases, then the baseline caveat, then sibling routing — four short sentences, no filler, nothing repeated from the schema verbatim.

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?

There is no output schema, and the description covers the key return signals ('changed or not' plus 'the diff') and the baseline edge case, which is enough to call it correctly. Minor gaps: diff format/size and what a snapshot overwrite means under destructiveHint are not described.

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 coverage is 100%, so parameter definitions already exist, yet the description adds operational meaning: pass your own agent id as `tag` so two watchers on the same page 'do not consume each other's changes.' That is a real usage rule the schema only hints at, not a restatement.

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 and resource ('check whether a public web page has changed') plus the payoff ('get the diff'), and contrasts with read_web_page and web_search. An agent can distinguish this from the adjacent page-reading and search tools without opening any schema.

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?

Names the concrete use case family ('watching one page over time: team page, pricing page, careers page') and gives explicit routing to two alternatives: read_web_page for contents, web_search for the open web. It also sets expectations for the first call so the agent does not misread a no-change baseline as a failure.

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

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

Adds genuinely non-obvious behavior: the first call only records a baseline and reports nothing, and without fresh=true the answer may come from a cache up to 90 days old, plus the paid-lookup cost of forcing freshness. What it does not address is the destructiveHint=true annotation — the description reads like a pure read, and although 'records a baseline' implies server-side state is written, it never says so plainly, leaving an agent to guess why the tool is flagged destructive.

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?

Four sentences, each load-bearing: capability, acceptable identifier, alternative routing, and the two operational caveats. The most costly mistake (stale cache on a scheduled watch) is placed last for emphasis rather than buried.

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?

No output schema exists, yet the description enumerates the classes of change returned and explains the empty-result case, which is exactly the ambiguity an agent would otherwise misread as failure. For a 2-parameter tool this covers everything needed to call it and interpret the result.

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 coverage is 100%, so the baseline is 3, and the description earns above that by quantifying the staleness the fresh flag guards against ('cached copy up to 90 days old, which is no use for noticing a move'), a concrete detail the schema lacks. It also restates the accepted identifier forms for `linkedin`, though that duplicates the schema example.

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 and resource ('Check one person's LinkedIn profile and report what has changed since the last check') and enumerates the change types reported (headline, company, move, open to work). It also names the boundary against a sibling ('for what they have posted use search_linkedin_posts'), so an agent can route correctly without opening either schema.

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?

Explicitly scopes use to 'watching a named person over time' and redirects post-related questions to search_linkedin_posts. It also pre-empts two predictable misuse cases: the first check returning no changes (normal, baseline recorded) and omitting fresh=true on a scheduled watcher.

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

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

The description describes a persistent preference write ("Record which publications the owner wants read..."), yet annotations declare readOnlyHint=true, i.e. no environment modification. Recording an allow/block decision is a state mutation that governs all future reading, so the annotation and the description directly conflict. The useful consent-gating context (only allowed senders are ever read) does not offset the contradiction.

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?

Three tight sentences, each doing distinct work: what is recorded, why it matters (consent gate), and how to call it. The most important constraint is front-loaded and there is no filler.

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?

With no output schema the description still covers the essentials: source of values, batching, and the fact that unlisted senders are not read. It omits what a second call does to prior decisions (replace vs. merge) and whether allow and block are mutually exclusive, which matters for a preference-setting tool.

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 coverage is 100% and the two array properties are documented as "Sender addresses to read from now on" and "Sender addresses to leave alone." The description still adds value by constraining the value format ("Pass the addresses exactly as find_my_newsletters returned them") and by framing both arrays as a single batch decision.

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 and resource ("Record which publications the owner wants read into their brain, and which they do not") and clearly separates itself from the sibling find_my_newsletters, which it names. An agent can tell instantly this is the write-the-preference tool versus the discovery/read tools.

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 real sequencing guidance: pull addresses from find_my_newsletters and pass them verbatim, and call once with all decisions rather than per sender. It never states a when-not-to-use condition or what happens on a repeated call, so it falls just short of explicit routing.

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

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

Annotations already mark this as a non-read-only, destructive operation. The description adds useful behavior beyond that: duplicate connections with the same type are a no-op, and the 'introduced' relationship has strict spelling and direction semantics. It does not explain why destructiveHint is true or what destructive side effect could occur.

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 front-loaded with the core operation and examples, then moves to edge-type semantics. It is somewhat verbose in the final warning about 'intro' or 'referral', but that warning carries real behavioral information.

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 a three-parameter mutation tool with full schema coverage and annotations, the description covers directionality, relationship naming, duplicate behavior, and the special introduction case. It does not discuss permissions, failure modes, or return behavior, but no output schema exists and the core call semantics are clear.

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 coverage is 100%, so the schema already documents all three parameters. The description still adds value by explaining where object IDs come from, illustrating from/to direction with examples, and specifying the exact 'introduced' relationship spelling and direction.

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 states a specific verb and resource — connect two graph objects with a directed edge — and gives concrete examples such as file-to-project and person-to-company. It clearly distinguishes the operation from creation or searching by explaining that it links existing objects.

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?

It tells the agent to use object IDs returned by create, search, or list operations, and gives a precise rule for introduction edges. It does not explicitly name alternatives such as disconnect_graph_objects for removal, but the intended usage context is clear.

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

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

Annotations only flag readOnlyHint=false and destructiveHint=true; the description adds substantive behavior beyond that – omitted colors/fonts/radius inherit the YouSpot kit defaults, logos are handled post-creation, and the return value is brand_kit_id. It does not explain why destructiveHint is true or what could be overwritten, which is the remaining gap.

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?

Four short sentences, all load-bearing: purpose and scope first, then the only-required-param and defaults rule, then the logo caveat, then the alternative routing. Nothing repeated.

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 a 7-parameter, nested-object mutation with no output schema, it covers the required-vs-optional split, defaults, and the return value. It leaves minor uncertainty around destructiveHint=true (e.g. whether an existing kit is overwritten) and how dark_mode/documents defaults resolve.

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 coverage is 71% and documented fields (colors, domain, radius, footer_text, documents) already carry their own meaning. The description adds the defaulting rule for omitted fields ('left out start from the YouSpot kit'), which is genuinely beyond the schema, though dark_mode and documents inheritance are only implied.

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 plus resource ('Create a brand kit') and scopes it ('by hand in the user's active space'), immediately separating it from the website-import sibling. An agent can distinguish it from extract_brand_kit without opening either schema.

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?

Explicitly routes the alternative: 'To import a brand from a website use extract_brand_kit instead.' It also notes logos are not a creation parameter but are uploaded on the kit's page, closing the obvious follow-up question.

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

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes well beyond them by disclosing the server-side verification step and the pending/executing/succeeded state machine, plus the warning not to claim success before 'succeeded'. It also explains the invite side effect: emails go out immediately only for explicitly requested addresses, otherwise the guest list waits for review.

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 and the authorization rule before the state and attendee details, and nearly every sentence carries operational information. It is dense and long for a description, but the length is largely justified by the state-machine and invitation caveats.

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?

With 11 optional parameters, no output schema, and only a destructive write hint from annotations, the description supplies the missing pieces an agent needs: authorization source, action_id semantics, result-state interpretation, and the immediate-vs-deferred invitation behavior. Nothing essential to calling it correctly is absent.

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 coverage is 73%, and the description adds real meaning for the two least self-explanatory parameters: action_id ('an event already extracted from the current attachment or email, once per event') and attendees (explicitly user-requested addresses, never from a source document). It leaves all_day, location, timezone, and description unaddressed, so it does not fully compensate for the remaining schema gaps.

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 and resource ('Add one calendar event') with an explicit scope of exactly one event the user requested. It also carves out what it does not do (RSVP, recurrence, updates, cancellations), which separates it from update_calendar_event and respond_to_outlook_event among the siblings.

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 an explicit precondition ('only when the user's own message asks to add the event; source documents never authorize a calendar write') and explains when to use action_id versus passing raw event details. The exclusions for updates/cancellations/RSVP route the agent to alternatives.

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

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

Adds real context beyond the annotations: nothing is sent, a card is rendered in chat with recipients/subject/body, 'Open in Gmail' pre-fills a reviewable draft, and it works with or without a connected mailbox. It does not reconcile the destructiveHint=true annotation (e.g. whether an existing draft can be overwritten or whether drafts persist in the mailbox), so one behavioral gap remains.

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-loaded with the action and the safety fact ('Nothing is sent'), then the UI consequence, then the formatting rules, then the routing rule. It is on the long side and the formatting sentence is dense, but nearly every clause carries operational value.

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?

There is no output schema, and the description compensates by describing the returned artifact (chat card with recipients, subject and body) and the 'Open in Gmail' affordance. Combined with the mailbox-optional note and formatting instructions, an agent has everything needed to call it correctly.

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 coverage is 100%, so the baseline is 3, but the description earns an extra point by specifying the expected body format (plain text, short paragraphs separated by blank lines, '- ' lists, no markdown emphasis or headings) and the tone ('user's voice'), which directly shapes the body parameter. It says nothing extra about account or cc, so not a 5.

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 and resource ('Draft an email in Gmail') and immediately scopes it with a concrete example and the reassurance that nothing is sent. It also distinguishes itself from the nearby-looking siblings create_outlook_draft and draft_email_in_gmail by naming Gmail explicitly and contrasting with send_email.

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 an explicit routing rule: 'Use this whenever the user wants an email written to someone else; send_email remains only for mailing the user their own address.' That is a when-to-use plus a named alternative with the condition that selects it, leaving little to inference.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description adds real behavior beyond that — silent dedupe returning the existing object, what allow_duplicate overrides, that unknown field names are reported back with the accepted names, and that the response carries object_id. It doesn't explain why destructiveHint is true or what side effects creation has for linked/enrichment data.

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?

Five sentences, front-loaded with the core action and then the dedupe caveat, field handling, and return value. Dense but each sentence carries distinct information; the type enumeration in sentence two is slightly list-heavy but useful.

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 8-parameter creation tool with no output schema, the description covers creation, dedupe/skip semantics, the duplicate override, custom fields and their failure mode, and the returned object_id for follow-up connect_graph_objects calls. Nothing an agent needs to call it correctly is missing.

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 coverage is already 100%, so the bar is higher, yet the description still adds value: it explains the purpose of allow_duplicate in user-intent terms and shows that 'fields' takes the type's own domain fields ('a domain_name's asking_price and source, a contact's phone') with explicit error behavior for invalid names.

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 opens with a specific verb+resource ('Create a new object in the user's graph') and enumerates the object kinds, which lets an agent distinguish it from siblings like set_graph_object_fields, connect_graph_objects, or get_graph_object. The scope is unambiguous.

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?

It gives a clear trigger ('Use when they ask to add something') and a precise rule for the tricky case: dedupe on type+name, and only set allow_duplicate=true when the user confirms a second one. It stops short of naming an alternative sibling (e.g., search_graph_objects to check first), so not a full 5.

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

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

Annotations declare a write (readOnlyHint=false, destructiveHint=true), and the description adds genuinely useful context beyond them: nothing is sent, the draft lands in Drafts, and chat shows a card with Open in Outlook. The 'Nothing is sent' reassurance sits in mild tension with destructiveHint=true and could have been reconciled explicitly, but it is clarifying rather than contradictory. Body-style expectations are also disclosed.

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-loaded with the core action and the no-send guarantee before mode and formatting guidance. Four sentences, all doing work, though the plain-text formatting rules are slightly verbose relative to the routing-critical content.

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?

No output schema exists, and the description compensates by describing what the agent/user will see (draft in Drafts folder, chat card). Both creation modes and the required body are covered; only the optional addressing and mailbox-selection parameters rely entirely on the schema.

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 coverage is 100%, so the baseline is 3, and the description does add real value by explaining the two parameter combinations (to/subject/body vs. reply_to_message_id/body with reply_all). However it never addresses cc/bcc/account, leaving the schema to carry those.

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 and resource ('Create a DRAFT in the user's connected Outlook mailbox') and immediately narrows scope by declaring nothing is sent. This clearly separates it from send_outlook_email and create_gmail_draft without needing to inspect schemas.

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?

Explicitly says 'Use this whenever the user wants an email written to someone from their Outlook mailbox,' and breaks the two modes into concrete invocation patterns (new email vs. reply with reply_to_message_id). It stops short of naming the sibling send_outlook_email as the alternative for actually sending, which would make routing fully unambiguous.

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

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

The description adds meaningful behavior beyond the annotations: LinkedIn and Twitter trackers become a daily cloud agent that emails digests, while web_page trackers run daily in the user's brain and email changes filtered by the prompt. It also instructs the agent to return page_url to the user for review and management. It does not cover permissions or rate limits.

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 front-loaded with the core purpose and then adds only useful routing, behavioral, and return-value details. Despite being longer than average, every sentence contributes necessary context for a multi-mode creation tool.

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, the description explicitly tells the agent what to return and how to use page_url. It also explains the different tracker behaviors and type-selection logic, leaving no major gap for correct invocation.

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 coverage is 100%, so parameter documentation is already strong. The description still adds value by explaining the relationship between url, query, and tracker_type for web_page trackers, including that query becomes a short label for the watched URL.

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 opens with a specific verb and resource: 'Set up a standing search.' It immediately clarifies the function with concrete examples and explains how the tracker type changes what is created.

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?

It gives clear routing guidance among tracker_type values: LinkedIn posts by default, tweets when requested, and web_page when a URL should be watched. It does not explicitly compare against sibling tools such as watch_web or manage_web_watch.

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

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

Goes well beyond destructiveHint=true: it discloses that the delete is soft (hidden from lists, search, and chat but retained and restorable), that only owned objects qualify, that the root user node is protected, and — crucially — that in chat it does not delete at all but returns instructions for a confirmation card. These are non-obvious behaviors an agent could not infer from annotations or schema.

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?

Five short sentences, front-loaded with the action, then the permission gate, then the destructive-behavior caveat. Every sentence carries information the agent needs; nothing is repeated from the schema or annotations.

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 a single-parameter mutation with no output schema, the description covers safety profile, identity resolution, ownership limits, and the unusual chat confirmation round-trip. There is no material gap left for an agent deciding whether and how to call it.

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 coverage is 100% and the single parameter is documented in the schema, so the baseline is 3. The description adds real meaning on top: where to get the object_id (search_graph_objects) and the ownership constraint on which ids are valid.

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 and resource ('Delete an object from the user's graph') and immediately qualifies it as a soft delete with retained data and restore capability, which distinguishes it in spirit from purge_graph_object. It does not explicitly name the bulk siblings (delete_graph_objects, delete_selected_graph_objects) or purge_graph_object, so an agent must infer the singular-vs-bulk split from the name alone.

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 an explicit trigger ('only when the user explicitly asks to delete or remove a specific object') and an explicit exclusion ('never to tidy up on your own initiative'), which is exactly the guardrail an agent needs. It also points to search_graph_objects as the way to obtain the id. It stops short of naming alternative tools for bulk deletion or permanent purge, so the routing across the delete family is incomplete.

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

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

Annotations already declare destructiveHint=true, but the description adds what the annotations cannot: the deletion is permanent, it operates at a scale of millions of records where partial cleanup is impractical, and crucially that in chat the tool deletes nothing itself — it counts records and hands the user a message whose click performs the deletion. That last detail materially changes how an agent should call and report the tool.

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 critical scoping and safety information is front-loaded in the first sentence and the alternatives follow logically. It is dense and nearly every clause carries information, though the parenthetical example and the scale remark slightly overlap with the permanence warning.

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 a destructive, zero-required-parameter bulk tool with no output schema, the definition covers everything an agent needs: selection modes, exclusivity, permanence, consent requirements, and the actual return behavior (counts plus a user-facing message). Nothing consequential is left to inference.

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 coverage is 100%, so the baseline is 3, but the description goes well beyond the schema by explaining the side-effect footprint of each parameter: import_id removes 'its contacts, companies, notes and files, the uploaded file and the import itself', and source removes 'every connection a LinkedIn export loaded and the people made from them'. It also clarifies the three parameters are alternative selectors, not combinable filters.

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?

Opens with a specific verb and resource plus scope: 'Delete EVERY object of one type from the user's graph, however many there are.' It immediately distinguishes the bulk case from single-record deletion, so an agent can tell it apart from delete_graph_object and delete_selected_graph_objects without opening a schema.

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?

Names the alternatives explicitly ('Deleting one object is delete_graph_object instead') and gives the trigger conditions for each mode: object_type for a whole category, import_id to undo one import, source for a LinkedIn export. It also sets a hard guardrail ('Use only when the user explicitly asked for these to go, never on your own initiative') and one-scope-per-call constraint.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses that the delete is soft and reversible, that objects disappear from lists/search/chat, that restore_graph_objects with the returned deleted_ids undoes it, and that only owned objects are removed (never the root user node) with the rest returned as skipped. That is exactly the consequence/undo/partial-failure detail an agent needs before a destructive call.

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?

Four sentences, each carrying distinct load — scope, permission condition, reversibility/undo path, sibling disambiguation, and ownership limits. The purpose and the guardrail are front-loaded, with no filler or repetition.

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 a destructive single-parameter tool with no output schema, the description covers what matters: the cap, the safety constraint, the undo path referencing the returned deleted_ids, partial-failure behavior (skipped), and even the chat-environment restriction. Nothing an agent needs in order to call it correctly is missing.

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?

There is one parameter at 100% schema coverage, and the schema already documents object_ids with the 200 cap, so the description largely restates it. The only marginal addition is that the ids must belong to the user's graph, which the description implies rather than specifies. Baseline 3 fits since the schema does the work.

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 and resource ('Delete a given list of objects from the user's graph') plus the scope limit of 200 ids per call. It explicitly positions itself against both siblings — 'One object is delete_graph_object; every object of a type is delete_graph_objects' — so an agent can pick the right tool without opening a schema.

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 an explicit positive condition (user explicitly asked for these particular objects to go) and an explicit exclusion ('never to tidy up on your own initiative'), plus the alternative tools for the single-object and whole-type cases. It even discloses an environment restriction ('Not available in the YouSpot chat'), which is routing information an agent could not infer elsewhere.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the crucial scope limit: only the single edge is removed and both endpoint objects survive. That directly answers the main fear an agent has about a destructive op. It doesn't say what happens if the edge is absent (error vs no-op) or whether the delete is reversible.

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?

One dense, front-loaded sentence carves out the exact scope, followed by a short actionable tip. No filler, nothing repeated from the title or schema.

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 a 3-param destructive edge deletion with full schema coverage and no output schema, this covers nearly everything. The remaining gap is failure behavior, whether a missing edge throws or is silently ignored, which matters when retrying a destructive call.

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 coverage is 100%, so all three params are already documented, and the description reinforces the directional semantics with the from -> to arrow notation, tying from_object_id and to_object_id together as edge endpoints. The gain over the schema is modest but real, and it clarifies that connection_type names the relationship rather than a generic type.

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 states a specific verb (Delete) and a precisely scoped resource (one connection/edge between two graph objects), not the objects themselves. The framing "the edge from_object_id -> to_object_id of the given connection_type, nothing else; both objects stay" cleanly separates it from the siblings connect_graph_objects and delete_graph_object.

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?

It gives explicit prep guidance: call get_graph_object first to learn an object's connections, their types, and their directions. That is a real prerequisite an agent would otherwise skip. It stops short of stating when not to use this tool (e.g. when you actually want to remove an object, use delete_graph_object), so it isn't a full routing guide.

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

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

Annotations already declare destructiveHint=true, but the description goes further by specifying the consequence: the action is not undoable and deleting a HubSpot portal also deletes every record it synced. That is exactly the collateral-damage context an agent needs before an irreversible call, beyond what the boolean hint conveys.

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?

Four short sentences, front-loaded with what the tool does, then the danger, then the anti-pattern, then the trigger condition. No filler and nothing buried.

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 a destructive mutation with no output schema, the description supplies the irreversibility, the data-loss scope, the read-path alternative, and the invocation precondition. An agent has everything needed to call it correctly or avoid calling it.

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 coverage is 100%, so both `key` and `account` are already documented in the schema, including the conditional requirement on `account`. The description adds only the soft hint 'naming what', which does not materially extend the schema. Baseline 3 applies.

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 and resource ('Disconnect one connected account') with the singular scope made explicit. It also names the sibling tool it must not be confused with, so an agent can distinguish it from list_integrations without opening either schema.

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 both a negative rule ('Never call this to check anything; call list_integrations for that') and a positive gating condition ('Only call it when the user has asked to disconnect, in their own words, naming what'). This is explicit when/when-not plus the named alternative.

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

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

Beyond the readOnlyHint annotation, the description explicitly states that the tool creates nothing, turns nothing on, and is safe to call as soon as the request is clear. It also discloses edge-case behavior, like still drafting with an empty trigger.from when no address exists, which gives the agent a clear mental model of side effects and limits.

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 dense but every sentence earns its place. It front-loads the core action and scope, then provides conditional guidance without tangents. Despite its length, it remains tightly organized and directly actionable.

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?

The description is complete for a draft-creating tool without an output schema. It covers scope, safety, trigger conditions, parameter overrides, address handling, and conflict resolution with the user. An agent has enough information to select and invoke the tool correctly in the described scenarios.

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?

Although schema coverage is 100%, the description adds significant parameter-level guidance: when to pass schedule/trigger overrides, how to populate trigger.from from address lookup, and what to do if no address is on record. This goes well beyond the schema's structural descriptions and directly informs correct invocation.

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 states a specific action: drafting a standing errand in the YouSpot chat so the user can enable it with one tap. It also distinguishes the tool's behavior from merely sending reminders by clarifying it creates nothing and turns nothing on, making its purpose unambiguous relative to sibling tools.

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?

The description gives explicit trigger conditions with concrete examples ('tell me when...', 'every morning...', 'notify me...'). It also names alternative actions when appropriate, such as using search_graph_objects or search_connections for address lookup, or asking the user with ask_user when two people match. This is strong when-to-use guidance.

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

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

The annotations already declare readOnlyHint=false and destructiveHint=true, so the description does not need to restate basic safety. It adds valuable behavioral context beyond annotations: nothing is sent, watermarked drafts are refused until unlocked, the legacy-grant limitation is surfaced at call time, and the return value is a link to the draft. It does not explain what the destructive hint specifically covers, but it does not contradict the annotations either.

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 front-loaded with the main action and safety statement, then covers the unlock requirement, grant limitation, and return value in compact sentences. Every sentence adds relevant information for correct invocation.

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 a four-parameter write-like tool with no output schema, the description is complete enough: it explains the generated-email source, the no-send behavior, the unlocking prerequisite, the legacy-grant constraint, and the return value. Remaining parameter details are fully covered by the rich schema.

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 100%, so the schema already documents all four parameters. The description adds minimal extra meaning, mainly reiterating that artifact_id comes from generate_email and that recipients were named by the user; it does not add syntax or edge-case guidance 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 states a specific verb and resource: putting a generated email artifact into the user's Gmail drafts. It distinguishes this from sending by saying 'Nothing is sent' and ties the artifact to generate_email, so an agent can differentiate it from siblings like send_email and create_gmail_draft.

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?

It gives clear context for when to use the tool: with an artifact_id from generate_email, addressed to named recipients. It also states two important preconditions — the email must be unlocked and the mailbox must be connected under a legacy modify grant — though it does not explicitly name an alternative for drafting non-generated emails.

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

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

The description states the tool writes drafts and saves them as notes in the user's brain, which modifies state, while the annotations declare readOnlyHint=true ('the tool does not modify its environment'). This is a direct contradiction of the safety profile an agent would rely on when deciding whether to invoke it. Annotation Contradiction flagged.

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-loaded with the core action and idempotency rule, then triggers, the sibling alternative, and output formatting. It is longer than most definitions, but each clause carries an instruction the agent must follow (error handling, link syntax, brand-brief exception) rather than padding.

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 a no-parameter, no-output-schema tool, the description covers the mutation semantics ('left as they are'), the no_plan error path, the fact that nothing is posted externally, and the two output-formatting variants (normal vs. in_brand_brief). Nothing needed to invoke or render the result is missing.

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 tool takes zero parameters and the schema is empty at 100% coverage, so per the rubric the baseline is 4. There is nothing parameter-level the description could add beyond the implicit 'this week' scoping, which it does state.

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 names a specific verb+resource+scope: 'Write every post in this week's post plan as a draft... saved to their brain as a note per post and linked to the plan.' It is clearly distinguishable from siblings like get_my_plan (read the plan) and plan_generation (create the plan).

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?

It gives literal trigger phrases ('write the posts in my plan', 'draft this week's posts'), names the alternative for the adjacent case ('For one post from finished work that is not on a plan, use the restate skill instead'), and routes the no_plan error ('offer to make one first'). When-to-use and when-not-to-use are both explicit.

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

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

The description goes well beyond the annotations by explaining that nothing posts, where the draft is saved, what older Slack installs show, and what the Send button does for channels where the bot is present. It also specifies the user's voice and formatting conventions, which is valuable behavioral context for a drafting tool.

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 front-loaded with the core action and non-posting behavior, followed by usage, fallback behavior, and style guidance. It is dense but mostly earns its length; the fallback UI explanation is useful but slightly niche.

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 a drafting tool with no output schema, the description is complete: it covers what happens, where the draft goes, how to invoke it, when to re-invoke it, and how the text should be written. The schema fully covers parameters, so no important calling context is missing.

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 100%, so all five parameters are already documented in the schema. The description adds some destination clarity for to and channel_id, but does not explain team_id or thread_ts beyond what the schema provides, so the baseline of 3 is appropriate.

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 states a specific verb and resource: write/draft a Slack message for a person or channel. It also clearly separates this from sending by saying 'Nothing posts' and explaining that the result is saved as a draft in the user's own Slack.

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?

It gives clear triggering guidance: use whenever the user asks to write, draft, or prepare a Slack message, and call again with revised text for changes. The non-posting behavior implies this is not the send tool, but it does not explicitly name send_slack_message as the alternative when the user actually wants to send.

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

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

Adds real behavior beyond the annotations: nothing is published, the chat renders the original post above the reply, and Copy/Reply-on-X opens X's composer prefilled. That resolves the ambiguity left by destructiveHint=true, which would otherwise suggest a live write to X. It stops short of stating auth requirements or whether a prior draft is replaced or duplicated on re-invocation.

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?

Four short sentences, front-loaded with what the tool does, then the non-posting behavior, then the trigger, then the style constraints. Nothing is redundant with the name or title.

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?

Two required params, full schema coverage, no output schema. The description covers what happens in chat, what the user sees, and the composition rules, which is everything an agent needs before calling it.

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 coverage is 100%, so both parameters are already documented as baseline. The description still adds constraint semantics the schema lacks: write in the user's voice, max 280 characters, no hashtags — guidance that directly shapes the `text` value.

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 and resource ("Write a reply to a post on X") and immediately scopes it as a draft-only operation, so an agent can distinguish it from any send/post capability. No sibling tool competes for this action, and the outcome is concrete.

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 an explicit trigger ("whenever the user asks you to reply to, answer or respond to an X post") plus iteration behavior ("call it again with the revised text when they want changes"). Both the entry condition and the re-invocation pattern are spelled out rather than inferred.

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

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

Goes well beyond the annotations: only empty fields are filled, user-written data is never replaced, results say which fields were filled, cached data fills immediately while the remainder completes asynchronously, and there is a daily limit. The 'nothing the user wrote is replaced, so it needs no approval' line sits in mild tension with destructiveHint=true, though it does not directly deny that the tool mutates the graph (readOnlyHint=false is consistent).

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-loaded with purpose followed by per-type behavior, batching, and the rate-limit caveat; nearly every sentence carries operational information. It runs a bit long and could split the batch semantics into a tighter clause, but there is no filler.

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 a mutation tool with no output schema, it covers what changes, what is preserved, what is returned, sync vs async completion, and a usage guardrail. An agent has everything it needs to call it correctly and to set user expectations.

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 100%, so the baseline is 3; the description still adds real meaning by explaining that 'domain' applies only to a company that has none yet, and that 'object_ids' is the batch alternative to 'object_id' with a 200 cap and background-fill behavior.

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 (enrich/fill empty fields) applied to a specific resource (company, contact, or web link in the user's graph) and anchors it to a known UI action ('the same as the Enrich button'). It also explains the per-type lookup key (website / LinkedIn or email / re-read page), which separates it from siblings like set_graph_object_fields and create_graph_object.

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?

Explicitly says when to use it ('when the user asks to enrich, fill in or flesh out a specific record'), how to handle multiple records (up to 200 ids, background completion), and when NOT to over-apply ('do not run it across the whole graph unasked'). The single-vs-batch routing is spelled out rather than inferred.

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

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

Beyond the annotations, the description discloses credit cost, when charging occurs, expected duration, that the new kit requires user review, and retry behavior. These are material behavioral details for a costly mutation tool and are consistent with destructiveHint=true.

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 front-loaded with purpose and behavior, then moves through cost, duration, sibling guidance, retry prohibition, and return values. Every sentence conveys actionable information with no wasted text.

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 the tool's cost, delay, mutation behavior, and sibling alternatives, the description provides all context an agent needs before invoking it. It also names the returned fields even though there is no output schema.

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?

There is only one parameter and schema description coverage is 100%, so the schema already explains website_url adequately. The description reinforces that it reads a public website but adds no further syntax or format detail 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 states a specific verb and resource: reading a public website and saving its brand assets as a new brand kit. It clearly distinguishes this extraction flow from retrieving existing kits by directing the agent to check list_brand_kits first.

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?

It gives explicit routing guidance: call list_brand_kits first and reuse a matching website's kit unless the user explicitly wants another extraction. It also states a clear retry prohibition: do not call this again to retry.

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

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

Annotations only declare readOnlyHint=true; the description adds concrete behavioral context beyond that: cost (1 credit per call), PDF support, the batch limit (five), and that full_content switches output to Markdown. It doesn't describe pagination, rate limits, or failure modes on unreachable pages, so it's strong but not exhaustive.

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-loaded with the core purpose and scope, then alternatives, then output mode, then cost. No filler sentences, though the objective example adds mild redundancy with the schema description. Efficient overall.

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 a read-only extraction tool with no output schema, the description covers the key decision points: scope, alternatives, output format options, PDF support, and cost. Minor gaps remain around error handling and whether results are per-URL tagged, but the agent has enough to call it correctly.

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 coverage is 100%, so the parameters are already documented. The description reinforces semantics for objective with a concrete example ('the price of each plan') and explains full_content's effect, but this is largely restating schema-level detail. Baseline 3 is appropriate when the schema carries the load.

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 (extract) and resource (web pages), defines the scope (up to five public pages at once), and explicitly differentiates from the sibling read_web_page by calling out velocity and cost advantages. An agent can distinguish it from read_web_page without inspecting the schemas.

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?

Explicitly names an alternative (read_web_page) and the condition that selects this tool: 'pulling specific facts'. Also explains the full_content fallback for whole-page retrieval and cites the cost (1 credit). This covers when-to-use, when-not, and the alternative.

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

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

Annotations declare readOnlyHint=true, so the safe read nature is already known. The description adds valuable behavioral context: it uses the ProspectFinder engine, handles multiple criteria in a single query, returns specific fields, and includes a result_id for rendering live prospect_list cards. No contradiction with 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 moderately long but every sentence earns its place: functionality, examples, return fields, usage boundaries, and result_id handling. It is well structured with no redundancy. Slightly dense but appropriate for the tool's complexity.

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 there is no output schema, the description fully compensates by specifying the return fields (name, domain, employee count, description) and the result_id behavior. It also covers input semantics, usage context, and post-processing steps, leaving no critical gap for an agent to invoke the tool correctly.

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 100%, covering both query and limit clearly. The description adds extra semantic value by illustrating the plain-English query format with three concrete examples and listing the dimensions it handles. Limit semantics are left to the schema, which is sufficient.

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 uses a specific verb and resource: 'Search for companies by describing them in plain English.' It clarifies the scope (discovering companies 'out in the world') and differentiates itself from sibling tools by explicitly stating the alternative for known companies/people. Concrete examples make the tool's behavior unmistakable.

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?

The description states exactly when to use this tool ('for discovering companies out in the world') and when not to ('for companies/people the user already knows, use their graph and connection tools instead'). It also mentions the follow-up action of adding results to the graph, giving the agent a clear workflow.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description goes further and discloses the return surface (linkedin_url, confidence on a 0-10 scale, a confident boolean) and how to hedge when confidence is low, which is meaningful behavioral context. It omits any note on resolution failure modes or latency, so not a 5.

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 capability, then usage, then output-handling guidance, with no filler. It runs a bit long in a single breath and the output-presentation sentence overlaps with what an output schema would normally carry, but every sentence carries actionable information.

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?

With no output schema, the description is the only source explaining what comes back (linkedin_url, confidence, confident) and how to interpret it. Combined with the usage trigger and ambiguity guidance, an agent has everything needed to invoke and report correctly.

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 100%, so both parameters are already documented in the schema. The description's mention of accepted handle formats and when to supply context mainly restates the schema rather than adding syntax or format detail. Baseline 3 is appropriate.

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 and resource: resolving the LinkedIn profile of the person behind an X handle. The clause 'not just the user's own' carves it out from the sibling get_twitter_profile / get_my_tweets territory, so an agent can distinguish it without opening the schema.

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?

Explicit trigger conditions are given ('when they give an @handle or an x.com link and ask for that person's LinkedIn, or who they are professionally'), plus a concrete rule for the optional context parameter when the handle is ambiguous. It even prescribes downstream behavior based on the confidence flag.

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

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

Annotations only declare readOnlyHint, but the description adds substantial behavioral context: it explicitly says no message bodies are read and nothing is changed, then defines the semantics of the returned `status` values ('undecided'/'allowed'/'blocked') and of `classification` ('newsletter'/'promotion'), including that classification is only a guess used for sorting and that the owner decides. That is exactly the kind of context annotations cannot carry.

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?

Content is front-loaded: the core action and the read-only guarantee come first, then the output-field semantics, then the presentation instruction. Some sentences are ornate ('this is the question, not the answer'), but each carries real meaning and nothing is padding.

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?

With no output schema, the description does the work of explaining the return shape — sender list, arrival/open counts, `status`, and `classification` — which is more than most tools provide. Minor gaps remain: no mention of the `days` parameter, no pagination or volume/limit behavior, and no explicit pointer to the sibling that reads or records decisions.

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?

There is a single parameter (`days`) with 100% schema description coverage, so the schema already documents the lookback window and its default. The description never mentions the time range, so it adds nothing beyond the structured field; baseline 3 applies when the schema does the heavy lifting.

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 and resource: it scans connected mailboxes for newsletters and returns the publications, arrival counts, and open counts. It also implicitly distinguishes itself from the reading/deciding siblings with 'reads no bodies and changes nothing: this is the question, not the answer', though it never names read_my_newsletters or choose_my_newsletters explicitly.

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 clear usage context — it is the survey/question step, and the closing sentence prescribes exactly what to do with the result (show undecided first, flag promotions, ask which to read). It stops short of naming the sibling that performs the actual reading or the one that records the decision, so the agent must infer the handoff.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: paths are limited to deliberate relationships (excluding bulk-import and system-inferred edges), the maximum length is 3 hops, and an empty list is returned when no connection exists. It also explicitly instructs the agent to report no-connection honestly and never invent a path, which is a valuable guardrail.

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 information-dense with no redundancy: it packs in scope, an example, an exclusion rule, and return behavior in four sentences. Each sentence earns its place, and the critical constraints (max 3 hops, empty list honesty) are clearly emphasized.

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 the simple 2-parameter schema and no output schema, the description covers what the agent needs to invoke the tool correctly: input semantics, path length, edge inclusion rules, return shape, and the no-connection edge case. The example also clarifies the expected path structure sufficiently for downstream use.

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 already fully documents both parameters as exact object_ids with clear descriptions, so schema coverage is 100%. The description adds useful context about graph objects and hops, but it does not add new parameter-level syntax, formats, or constraints beyond what the schema provides.

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 identifies a distinct operation: finding the shortest path between two graph objects using only deliberate relationships, up to 3 hops, with a concrete example. It is specific about the resource and behavior, though it does not explicitly differentiate itself from sibling tools like search_connections or mutual_connections.

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?

The description implies when to use the tool—when checking whether and how two objects are connected—but provides no explicit when-to-use guidance or exclusions. It does not mention sibling alternatives or explain when a different connection-related tool would be preferable.

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

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

The annotations already declare a non-read-only, destructive operation, and the description adds substantial context beyond them: no email is sent, drafts are capped at 20/day, the call costs 1 credit except on Solo/Pro, and the result is an artifact id. It also warns not to call again to retry, which is valuable operational guidance.

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 purpose is front-loaded and most sentences carry necessary template or behavioral detail. The long template enumeration makes it dense and somewhat run-on, but little is pure filler for a tool with seven templates and nine parameters.

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 a complex, nested-parameter tool with no output schema, the description covers the important behavioral facts an agent needs: template shapes, body format, defaults, cost/rate limit, return value, and next step. The only minor gap is saved_template_id, which the schema already explains.

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 coverage is 67%, so the description usefully goes beyond the schema by listing exactly which props each template accepts, the markdown-versus-blocks exclusivity, header/align defaults, and brand_kit_id fallback behavior. It omits saved_template_id semantics, though the schema itself documents that parameter.

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 first sentence states a specific verb and resource ('Render one branded email') plus the outcome ('save it to the user's files'), and immediately clarifies it does not send. It distinguishes itself from email-sending siblings by saying 'Nothing is sent' and directing the artifact to draft_email_in_gmail.

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?

It clearly tells the agent to pick a template whose shape fits the job and gives the follow-on action ('call draft_email_in_gmail with it'), plus an explicit retry exclusion. It does not explicitly compare itself to create_gmail_draft or send_email, but the no-send scope and next-step routing cover most selection needs.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=true, so the description carries the burden of explaining what actually happens. It does: the card renders the whole document, the file is not something the user has to open, and there is no watermark/lock/paywall — behaviour an agent cannot infer from the schema. It does not address why destructiveHint is true or whether an existing document with the same title is overwritten, which is the one meaningful gap.

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-loaded with the action and the scope, then parameters, then rendering behaviour, then the alternative — a sensible order. A few sentences ('nothing to unlock and nothing to pay') are defensive padding that could be cut without losing information.

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?

No output schema exists, and the description compensates by explaining what the user sees (a card rendered in the brand) and the important side-constraint not to also paste the markdown into the reply. Between that and the explicit alternative routing, an agent has enough to call this correctly and to avoid the most likely failure mode.

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 100%, so title, markdown and brand_kit_id are already documented, including the same 'first heading otherwise' default and the same reference to list_brand_kits. The description restates these without adding format, length limits or validation details, so baseline 3 applies.

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 and resource ('Write one document in the user's brand and save it to their files') and immediately bounds the scope with a concrete enumeration of content types (to-do list, checklist, plan, notes, brief, summary). It also names the sibling it supersedes for other intents, so the agent can distinguish it from generate_pdf without opening either schema.

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?

Explicit routing: use this when the user wants to read something in chat, use generate_pdf instead when they want to print, attach or send. It adds a retry exclusion ('Do not call this again to retry'), which is a use-condition no other field carries.

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

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

Goes well past the annotations by disclosing the 20-drafts-per-day cap, the 1-credit cost (free on Solo/Pro), the return values (artifact id and page count), and the retry prohibition. Those are the operational constraints an agent needs before invoking a write tool, none of which are in the annotation block.

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-loaded with the action and scoped tightly to what matters, with no filler. The template enumeration is a dense run-on that would read better as a list, but every clause carries information an agent needs.

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 11-parameter tool with nested objects and no output schema, the description covers body format, template-specific inputs, defaults (brand kit, footer, title), cost, limits, and return values. Nothing needed to call it correctly is missing.

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 coverage is already 82%, yet the description adds real meaning: which props each template consumes, the 30-item limit, that all line-item fields are strings, that dates are YYYY-MM-DD, that markdown and blocks are mutually exclusive, and that the first heading becomes the title. That is substantial semantics beyond the schema, especially for the undescribed template_id enum.

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?

Opens with a specific verb+resource ('Render one branded PDF in a brand kit and save it to the user's files') and enumerates the document types it covers, which separates it from siblings like generate_markdown or generate_og_image. An agent knows exactly what it gets back: a saved PDF artifact.

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 concrete selection guidance — which template handles invoices vs statements vs freeform docs, and how to handle an unfamiliar ask by routing it through report/letter/proposal. Adds a 'do not call this again to retry' rule. Missing an explicit contrast with the markdown-generation sibling, so not a full 5.

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

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

Annotations only provide readOnlyHint=true, so the description carries most of the burden and delivers: rate limit (20 drafts/day), credit cost and plan exemptions, template/prop contracts, mutually exclusive body formats, audience semantics, and explicit non-publication/non-send guarantees. This is unusually rich behavioral disclosure beyond the structured fields.

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?

Dense but front-loaded: the core purpose and scope come first, then constraints, templates, format, cost, and the voice prerequisite. Every sentence carries operational information, though the run of short declarative sentences reads more like a checklist than prose.

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 a 7-parameter tool with nested objects and no output schema, the description covers creation rules, format, cost, limits, and ordering well. It stops short of saying what the call returns (file name/location, draft id), which an agent would want given there is no output schema.

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 coverage is 71%, and the description adds genuinely new meaning: which prop fields each template requires ('post' takes signoff; 'digest' takes intro, signoff) and the markdown-XOR-blocks rule, neither of which appears in the schema. The audience line largely restates the enum, which keeps it from a 5.

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 and resource: 'Draft one Substack post and save it to the user's files.' An agent immediately knows it produces a draft artifact rather than reading existing posts. However, it never explicitly differentiates itself from related siblings such as draft_my_planned_posts or plan_generation, so it stops short of the 5 bar.

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 strong sequencing guidance ('When Substack is connected, call get_my_substack_voice first') and a clear when-not ('Do not call this again to retry'), plus cost and rate-limit context. It does not name alternative tools for the case where a draft already exists, but the operational context is clear.

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

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

The annotations declare readOnlyHint=false and destructiveHint=true, so the agent already knows this is a mutation with destructive potential. The description adds useful behavior around saved_template_id seeding and replacement, plus the return value artifact_id, but it does not explain the scope of destructive effects or what may be overwritten.

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 front-loaded with the core purpose and remains reasonably compact despite the long first sentence. “Views are free: no watermark and nothing to unlock” is product context that does not help an agent decide or invoke the tool, keeping it from a 5.

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 a five-parameter tool with 100% schema coverage and no output schema, the description covers purpose, inputs, template-seeding behavior, and the returned artifact_id. The main remaining gaps are explicit routing against related tools and a fuller warning about the destructiveHint=true behavior.

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 coverage is 100%, so the schema already documents all five parameters, establishing a baseline of 3. The description adds meaning beyond the schema by explaining that source is the whole view in the view language, spec_version is the library version, title/state are optional, and saved_template_id seeds values while passed values replace them.

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 states a clear verb and resource: save a view in the view language that renders with live data, with concrete examples like dashboard, Markdown document, feed, and generated emails/images. It is clearly a save/create-view operation, but it does not explicitly distinguish itself from sibling tools such as update_view or show_view.

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?

Usage is only implied by “Save a view the user wants to keep” and by noting that saved_template_id comes from a template saved earlier. It does not state when to use this versus update_view, show_view, list_templates, or save_as_template, nor does it give explicit prerequisites.

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

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

Annotations include readOnlyHint=true, so the agent knows it's a safe read. The description adds valuable behavioral context: it specifies what fields are returned (template, brand, status, inputs for own drafts) and the purpose (to enable editing via generators). It doesn't describe the exact return structure, but for a read tool with no output schema, this is sufficient.

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 a single sentence that front-loads the core action and resource, then lists the key data returned and the purpose. It is efficient, though slightly long, but every clause adds information. No fluff or repetition.

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 a read-only tool with one parameter and readOnlyHint, the description covers the essentials: what it returns, the caveat about own drafts, and the intended use case. It doesn't cover error handling or return format, but those are minor for a simple read operation. The description is complete enough for an agent to call it correctly.

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 schema already fully documents the single parameter artifact_id, including its source (from list_artifacts or a generator). The description adds no additional detail about the parameter itself, but given 100% schema coverage and one simple parameter, the baseline of 3 is appropriate.

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 the action ('Read'), the resource ('one generated image, email or PDF'), and the specific data returned (template, brand, status, and inputs for user's own drafts). It distinguishes itself from siblings like list_artifacts (which lists) and generator tools (which create) by focusing on reading a single artifact by ID.

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?

The description implies when to use this tool: when you have an artifact_id and need details of a generated item, especially to retrieve inputs for regenerating with changes. It doesn't explicitly name alternatives or state when not to use it, but the context of siblings and the focus on reading vs. listing or generating is clear enough.

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

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

Annotations include readOnlyHint=true, so the description doesn't need to state safety. The description adds no behavioral detail beyond the annotation, but the annotation already covers the key trait. No contradiction.

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 a single short phrase, front-loaded and free of fluff. It is concise, though it could add a bit more context without becoming verbose.

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 a simple read tool with one parameter and a readOnlyHint annotation, the description is adequate. It doesn't explain return format, but no output schema exists and the tool is simple enough that an agent can infer the return from the resource type.

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 100%: the only parameter brand_kit_id is described as 'A brand_kit_id from list_brand_kits.' The description adds no additional parameter meaning, but the schema already provides sufficient guidance.

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 'Get brand kit' clearly states a specific verb and resource, and the title 'Get brand kit' reinforces it. It distinguishes from siblings like list_brand_kits and create_brand_kit, though it doesn't explicitly name them.

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?

The description implies usage: call this to retrieve a single brand kit by ID. It doesn't explicitly state when to use this vs list_brand_kits or update_brand_kit, but the verb 'get' and the parameter description referencing list_brand_kits provide some context.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does so well: default scope is each account's main calendar, count_only sweeps up to 12,500 events versus a normal listing, max_results defaults to 10 and caps at 250, Outlook events carry a web_link, and the no-calendar-connected error state is described with remediation.

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-loaded with the return shape and scope, then walks through the parameters in a logical order. It is long (~190 words) and the count_only and calendar-selection paragraphs could be tightened, but nearly every sentence carries actionable information rather than filler.

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?

With 8 optional parameters and no output schema, the description compensates by describing the returned fields, defaults, caps, and the special count_only return shape. An agent has everything needed to call this correctly, including the failure path.

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 coverage is 100%, so the baseline is 3, but the description genuinely adds semantics beyond the schema: RFC3339 example format, the concrete 'what's on my calendar tomorrow' mapping to time_min/time_max, that past ranges work, that query matches titles/descriptions/attendees, and a 'Family' example for calendar_id.

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?

Opens with a specific verb+resource (list events from the user's connected calendars) and immediately scopes it (Google and Outlook together, ordered by start time). It enumerates the returned fields, which makes it trivially distinguishable from siblings like create_calendar_event, list_google_calendars, and list_outlook_calendars.

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?

Explicit routing guidance throughout: use count_only=true for 'how many meetings' over long ranges, pass calendar_id or all_calendars to read non-default calendars, get Outlook calendar ids from list_outlook_calendars, and with no time range it returns upcoming events. It even names the fallback when no calendar is connected (link to the integrations page).

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. Beyond that, the description adds essentially nothing: it does not say what a 'relationship card' contains, whether the tool requires a resolved company node, or how it behaves when neither domain nor object_id is supplied (0 required params). Minimal added value over 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?

It is a single short sentence, so nothing is wasteful in length. However, the phrasing is awkward and self-referential ('a view drawing a company_card'), which impedes rather than aids comprehension, so brevity does not translate into clarity.

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 a 2-parameter lookup tool with no output schema and only a readOnlyHint annotation, the description should explain what the returned card is and how to identify the target company. It leaves the domain/object_id selection and the meaning of 'relationship card' entirely unspecified.

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 100%, so both parameters are documented in the schema itself. The description does not clarify the domain-vs-object_id relationship, nor which one is preferred or what happens when both or neither are given, so it neither helps nor hurts beyond the baseline.

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 names the resource ('relationship card for one company') and hints at what it feeds ('a view drawing a company_card'), but there is no clear verb and the phrase 'for a view drawing a company_card' is circular and muddled. It does not explicitly distinguish itself from siblings like get_person_card or get_object_card, forcing the agent to infer the company-vs-person-vs-object split from the name alone.

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?

There is no statement of when to use this tool versus alternatives such as get_person_card, get_object_card, or get_domain_info. The only contextual hint ('for a view drawing a company_card') implies it is a rendering dependency, but no conditions, prerequisites, or alternatives are given.

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

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

Beyond the readOnlyHint annotation, the description discloses subtle response behavior: found:false carries the imported-connection count, and no_imported_data means nothing was searched, so the agent should report a missing import rather than a missing person. This is valuable non-obvious behavior that annotations alone do not provide.

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?

Four sentences, each carrying distinct value: what the tool returns, when to use it, how to identify the target, and the important edge-case response. The most important information is front-loaded, and there is no filler.

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?

The description covers the tool's purpose, scope, invocation guidance, and the key false-response edge case despite having no output schema. It does not fully describe the success response structure, but the listed profile fields provide enough framing for an agent to understand what will come back.

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 coverage is 100%, so the baseline is 3, but the description adds matching semantics: name is the general identifier and linkedin_url is specifically for an exact match. This helps the agent choose between the two optional parameters more effectively than the schema alone.

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 identifies the resource (a LinkedIn connection profile) and the specific data returned (work history, education, skills, About summary). It distinguishes the tool from the broader search_connections sibling by framing this as the depth-focused follow-up.

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?

The description explicitly says to use this after search_connections when depth on a specific person is needed. It also gives practical guidance on how to identify the target (by name or linkedin_url), making the invocation context clear.

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

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

With readOnlyHint already present in annotations, the description still adds useful behavioral context: it summarizes previously imported LinkedIn data rather than querying live data, and notes the last import time. This goes beyond the annotation's generic read-only signal.

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 with no filler. The first sentence front-loads the core purpose and contents, and the second sentence provides a crisp usage directive. Every part earns its place.

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, the description explicitly lists what the tool returns: connection counts, invitation counts, message counts, last import date, and top companies. This is sufficient for an agent to know what result to expect. The sibling set is large, but the description's scope wording is clear enough.

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 tool has zero parameters and 100% schema coverage, so there is no parameter burden to bear. The description appropriately stays silent on parameters because none exist.

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 verb and resource: it provides an 'Overview of the user's imported LinkedIn data' and enumerates what it covers (connections, invitations, messages, last import date, top companies). This distinguishes it from related detail or search tools like get_connection_details or search_connections.

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?

It gives explicit guidance on when to use the tool: 'questions about the shape of their network as a whole, or how much data is loaded.' However, it does not mention specific alternatives or when not to use it, so it falls just short of a top score.

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

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

Beyond the readOnlyHint annotation, the description discloses that this is public registrar data, not the user's account data, and that it says nothing about the underlying company. It also surfaces the privacy-masking behavior where registrant fields may name a proxy rather than the real owner, which is a key behavioral caveat.

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?

Every sentence earns its place: the first defines the operation and outputs, the second gives precise usage rules with examples, the third states a hard exclusion, and the fourth adds the important privacy caveat. It is informative without filler.

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 a read-only tool with one required parameter and no output schema, the description covers what the call returns, exactly when to use it, when not to use it, and the main data-quality caveat. Nothing essential for correct invocation is missing.

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 already covers both parameters fully: the single 'domain' parameter has a clear description, an example value, and the full-URL normalization behavior. The tool description adds no additional parameter-level meaning beyond referring to a 'website domain', so the high schema coverage baseline of 3 is appropriate.

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 and resource: 'Look up the public registration (WHOIS) record for a website domain' and enumerates the exact fields returned. It also contrasts with general company research, which clearly distinguishes it from siblings like research_company and get_domain_value.

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?

Explicitly scopes usage with 'Use this ONLY when the user explicitly asks about the domain/WHOIS/DNS itself', provides concrete example queries, and gives a hard exclusion: 'Never call it for general questions about a company'. This is exemplary routing guidance.

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

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

Annotations provide readOnlyHint=true, so safety is covered. The description adds valuable behavioral context: US search data only, domain preferred over company name, and the exact metrics returned (volume, CPC, position, landing URL, share, totals). This goes beyond what annotations state, though it does not mention rate limits or data freshness.

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?

Two dense sentences front-load the core output, then provide usage guidance and input constraints. No wasted words, though the first sentence is long and packed with many data fields.

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?

With no output schema, the description enumerates return fields in sufficient detail for an agent to know what to expect. Pagination behavior is not described, but the limit parameter covers that need.

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 100%, so the schema already documents all parameters. The description's note about domain preference is already present in the schema, so it adds no additional parameter meaning beyond what structured data provides.

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 the specific resource: search keywords a website buys ads on (paid) and ranks for organically, with detailed data fields. It is easily distinguishable from sibling tools like get_domain_info and get_domain_value by the keyword focus and the explicit output metrics.

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?

The description includes an explicit 'Use this when...' clause enumerating user intents: keywords bought/bid on, ad spend, rankings, and competitor comparison. It lacks a when-not clause or named alternatives, but the guidance is concrete and actionable.

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

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

Annotations only declare readOnlyHint, so the description carries most of the load and does it well: it discloses the default extension set, that only the lowest-priced listing is returned, that for-sale domains may lack a price, that listing type (buy now/offer/auction) is unknown, and that registration fees are excluded. It stops short of saying anything about rate limits or response shape, but the caveats are the ones that would actually mislead an 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?

Front-loaded with the core action and output, then caveats, then sibling routing. A couple of clauses restate what the schema already documents (the default .com/.net/.org/.ai set), but no sentence is pure filler.

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?

With no output schema, the description must explain return values and does: availability states, USD asking price, marketplace, and the lowest-listing-only rule. Combined with the sibling routing and caveats, an agent has everything needed to call it and interpret the result.

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 coverage is 100%, so the baseline is 3; the description still adds value by tying the tlds default to user intent ('unless the user names other extensions, so mention any of those that are for sale'), which tells the agent how to act on results rather than just how to fill the field.

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 and resource ('check whether a domain name is for sale and what it costs') and enumerates the availability states it returns. It explicitly distinguishes itself from the two closest siblings, get_domain_value and get_domain_info, by naming them.

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 concrete trigger phrasings ('is cova.com for sale?', 'price for cinch.com') and explicit exclusions routed to alternatives: appraisal goes to get_domain_value, ownership to get_domain_info. Nothing is left to inference.

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

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

Annotations already carry the read-only safety profile, and the description adds substantial behavioral context beyond that: fresh appraisals can take up to a minute (latency), repeat lookups within 48 hours are cached and instant (caching/rate-limit relevant), and the reply must include report_url. It also discloses what the result contains (market value in dollars plus supporting signals).

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?

Three sentences, each earning its place: what it does and returns, when to use it, and the latency/caching/report_url behavior. Purpose is front-loaded and there is zero filler.

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?

With one fully-documented parameter, no output schema, and a read-only annotation, the description carries the full burden of explaining the return value — and it does: estimated market value in dollars with the signals behind it, plus the report_url handling. Nothing an agent needs to invoke it correctly is missing.

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 100%, so the baseline is 3. The description adds no extra meaning about the domain parameter beyond what the schema already provides (e.g., no format caveats or edge-case guidance), but it doesn't need to since the schema fully documents the single parameter.

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 opens with a specific verb and resource: "Estimate what a domain name is worth" — clear this is a valuation tool, not a domain-info tool. The listed signals (comparable sales, marketplace listings, appraisal model, SEO data) make it easily distinguishable from the sibling get_domain_info without needing to open either schema.

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 when-to-use conditions: "when the user asks what a domain is worth, whether one is a good buy, or to compare domain values." This is clear context, but it never names or excludes the closest alternative (get_domain_info), so it stops short of full when-not/alternative guidance.

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

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

The readOnlyHint annotation already marks this as a safe read operation, and the description adds meaningful behavioral details: the response includes the full plain-text body, with a documented edge case for header-only connections. This goes beyond the annotation and gives the agent realistic expectations for output content.

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?

Two concise, information-dense sentences. Key purpose and usage come first, and the behavioral exception is placed naturally without bloat. Every clause earns its place.

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 a simple two-parameter schema, full schema coverage, a read-only safety annotation, and no output schema, the description provides enough context: what it fetches, what the body looks like, the rare header-only case, and when to use it. An agent should be able to invoke this tool correctly with no additional guidance.

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 100%, so the schema fully documents both parameters. The description reinforces the role of message_id but does not add detail beyond the schema. Baseline 3 is appropriate because the description does not need to compensate for missing schema information.

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 states a specific verb and resource: 'Fetch one Gmail message by its id' from the connected mailbox. It also clarifies what the tool returns (full plain-text body, or headers/snippet for rare header-only connections), distinguishing it from sibling search_gmail_messages which returns only ids and snippets.

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?

The description explicitly names the intended use cases: reading a message found via search_gmail_messages, or analyzing a message_id from a triggering event. It also contrasts with search_gmail_messages by noting that search returns ids and snippets only, so an agent knows when to switch to this tool.

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

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

The description reveals that by default only the start of the transcript is included, and that passing transcript=true returns the full transcript instead. It also discloses the output contents (summary, attendees, time, space, link, transcript start), adding value beyond the readOnlyHint annotation.

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 compact and front-loaded, stating what the tool returns in the first sentence. The second sentence clarifies both parameters without unnecessary detail or repetition.

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?

Since there is no output schema, the description adequately enumerates the return contents and explains the default versus transcript mode. This is sufficient for an agent to know what to expect and when to use the transcript flag.

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?

Although the schema already has 100% parameter coverage, the description adds meaningful context: note can be an object id from get_granola_notes, a Granola note id, or a title, and transcript should be used when the user wants exact wording. This goes beyond the schema's brief descriptions.

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 the verb and resource: it reads one Granola meeting note and returns the full content. It also distinguishes itself from siblings like get_granola_notes by emphasizing a single note and listing specific fields returned.

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?

The description gives concrete guidance for choosing the transcript versus summary based on the user's request ('when the user asks what exactly was said'). It also explains that the note identifier can come from get_granola_notes, but it does not explicitly contrast this tool with search_granola_transcripts or other alternatives.

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

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

Annotations only declare readOnlyHint, and the description adds useful behavioral context: data is already synced, results are newest-first, the call is fast and does not invoke Granola. It does not discuss staleness or auth, but that is not required for a simple read-only list.

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?

Three sentences with no filler: the first front-loads the resource, ordering, and output fields; the second maps parameters to behavior; the third gives the follow-up route. Every sentence contributes.

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 a simple read-only list with four optional, fully documented parameters and no output schema, the description gives the important return shape, sort order, parameter semantics, and next-step tool. Nothing an agent needs to call it correctly is missing.

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 schema already covers all four parameters (100% coverage), so the baseline is 3. The description adds plain-language semantics for days, query, and attendee, explaining filtering behavior beyond the schema's field descriptions. Only limit is left entirely to the schema, which is acceptable.

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 opens with a specific verb and resource ('List ... Granola meeting notes'), states the result ordering ('newest first') and enumerates returned fields (title, time, attendees, space, link). It also names the sibling get_granola_note for drilling into one meeting, so an agent can distinguish list from detail retrieval.

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?

It clearly signals this is the lightweight path over already-synced notes ('Fast, no Granola call') and instructs follow-up with get_granola_note for summaries/transcripts. It does not explicitly contrast with search_granola_transcripts or state when not to use the tool, but the primary alternative is named.

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

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

Annotations already mark readOnlyHint=true, and the description adds meaningful context about the reported data: account, shared spaces, last sync, and brain note count. It does not overpromise or hide side effects; for a read-only status tool, this is sufficient.

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?

Two efficient sentences: the first front-loads the tool's purpose and data scope, the second gives a concrete usage trigger. Every sentence earns its place with no redundant boilerplate.

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 a zero-parameter read-only status tool, the description is complete. It enumerates the outputs an agent can expect, explains when to invoke it, and the absence of an output schema is adequately compensated by the explicit field list.

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 tool has zero parameters and the schema is fully covered, so the baseline is 4. The description's content about what is reported compensates for the lack of an output schema, and no parameter explanation is needed.

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 the tool reports Granola connection and sync status, listing specific data points: account, shared spaces, last sync time, and note count. This distinguishes it from siblings like get_granola_notes and search_granola_transcripts, which handle note content rather than status.

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?

Explicitly says to use it when a user asks why a meeting is missing or whether Granola is set up. It does not name alternatives or exclusions, but the use case is clear enough for an agent to select this over related Granola tools.

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