YouSpot

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

Goes well beyond the lone readOnlyHint=false annotation by describing three distinct outcome branches: no-sign-in connectors are added immediately, sign-in connectors return sign_in_url and must not be reported connected until finished, and already-added ones return the connector page. This is exactly the behavioral context an agent needs.

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 every sentence carries distinct operational meaning (gating rule, two branches, edge case). Slightly dense/run-on in places but nothing is wasted.

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?

Covers the happy path, the sign-in branch, and the already-added edge case for a one-parameter mutation tool. With no output schema, the description fully explains what the agent will receive and how to react.

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 'name' param is already documented as coming from list_connectors. The description reinforces the source but adds no syntax or format detail 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 and resource (add/connect a connector) and ties the input to list_connectors, which cleanly separates it from the enumeration sibling. An agent immediately knows this performs the connect action rather than listing.

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 gates invocation: 'Call it only when the user asked to connect that service,' and directs the agent to list_connectors for valid names. Both the when-to-use condition and the source of the argument 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 only signal that this is not read-only (readOnlyHint: false). The description accurately discloses the mutation and adds emoji-name format examples, but it does not mention permissions, idempotency, workspace/team disambiguation, or what happens on failure.

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?

A single sentence with a parenthetical example; every word earns its place and the core action is front-loaded. No filler or redundant restatement of the 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?

The tool is simple and has no output schema, so the short description is adequate for basic invocation when channel_id and ts are already known. However, it lacks guidance on how those identifiers are obtained, making it incomplete for an agent that must discover the message before reacting.

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 only 50%, but the description only adds meaning for the emoji parameter (examples of valid names). It does not explain channel_id or team_id, and ts is left as the schema's minimal 'The message's ts.'

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 action ('Add'), a specific resource ('a Slack message'), and the object ('an emoji reaction'). It also gives concrete emoji-name examples, making it unmistakably distinct from siblings like send_slack_message or get_slack_thread.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It does not mention that send_slack_message should be used for sending text, or that ts/channel_id must come from an existing Slack message lookup such as get_slack_thread or search_slack_messages.

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?

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?

Beyond the readOnlyHint: false annotation, the description adds a useful behavioral constraint: only unsent scheduled texts can be canceled. However, it does not mention what happens if the text has already been sent, whether cancellation is reversible, or any permission requirements, so some burden remains 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?

Two sentences with no filler; the action and condition are front-loaded, and the parameter source is provided 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 one-parameter cancellation operation, the description covers the operation, the condition, and the source of the identifier. It does not describe the response or error behavior, but no output schema exists and the operation is simple enough that this is a minor gap.

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 describes task_id as 'The scheduled text to cancel,' which is the baseline. The description adds important provenance for the value: it comes from the scheduling response or from list_scheduled_texts, going 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?

States the exact operation: canceling a text that was scheduled via send_text_to_user and has not been sent. This clearly differentiates it from other text-related tools like send_text_to_user and list_scheduled_texts.

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?

Tells the agent when it applies (scheduled, not yet sent) and exactly where to obtain the required task_id: from the scheduling response or list_scheduled_texts. It does not explicitly rule out alternatives, but its scope is specific enough that no close alternative exists among the siblings.

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, which is consistent with a tool that persists snapshots, so no contradiction. The description adds real behavioral context the annotations lack: the first call records a baseline and reports no change, and snapshots are kept per page and tag. It stops short of covering rate limits, snapshot retention, or diff format.

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 purpose, then statefulness, then the tag convention, then alternatives — each sentence carries distinct information with no filler. The alternative-routing sentence is compactly packed at the end where it belongs.

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 describes the return well enough to act on (a diff, with the first call reporting no change). Minor gaps remain around the shape of the diff and any error or rate-limit behavior, but nothing critical for invoking the tool 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 100%, so baseline would be 3, but the description adds operational meaning beyond the schema: it tells the agent to pass its own agent id as tag and explains the consequence (two watchers not consuming each other's changes). That is guidance the schema text only partially conveys.

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 since the last time this was called for it, and get the diff") and explicitly names the sibling tools it is not (read_web_page, web_search). An agent can distinguish it from the large sibling list immediately.

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 when-to-use profile ("Use for watching one page over time: a company's team or leadership page, a pricing page, a careers page") and routes to alternatives with conditions ("For the contents of a page use read_web_page; for the open web use web_search"). 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?

The description discloses important behavior beyond the annotations: the first check records a baseline and reports no changes; cached copies can be up to 90 days old without fresh=true; and fresh=true costs a paid lookup. These details align with readOnlyHint=false and give the agent essential execution 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?

The description is front-loaded with the core purpose, then covers input, alternatives, baseline behavior, and freshness rules in a compact form. Each sentence earns its place, and there is minimal 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?

Although there is no output schema, the description provides enough behavioral context: what changes are detected, what a first check returns, how to ensure current data, and which sibling tool to use instead. This is complete for a tool with one required parameter.

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 both parameters well, so the baseline is 3. The description adds extra meaning by explaining the 90-day cache staleness tied to fresh=false and by giving the username/URL input format and example context, which slightly exceeds what the schema alone 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 uses a specific verb and resource: "Check one person's LinkedIn profile and report what has changed since the last check." It also names the explicit alternative search_linkedin_posts for posted content, which helps distinguish it from a key sibling tool.

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 to use this for "watching a named person over time" and to use search_linkedin_posts for what they have posted. It also gives concrete scheduler guidance: set fresh=true when running as a scheduled watcher, because otherwise cached data may be up to 90 days old.

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?

The description adds meaningful behavior beyond the readOnlyHint annotation: it discloses the split between new and already-reported items, and explicitly states that on a scheduled run the tool should "report only the new items and stay silent when there are none." This is valuable context for an agent deciding how to present 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 front-loaded: the first sentence gives the core function, the second gives the use case, the third gives scheduling behavior, and the fourth states alternatives. Every sentence contributes distinct information with no redundancy or 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 full schema coverage, a readOnlyHint annotation, and clear sibling distinction, the description is complete enough. It explains what the tool covers, when to use it, how it behaves on schedules, and which alternatives to choose for other scenarios. The absence of an output schema is mitigated by the description's explanation of the new vs. previously reported split.

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 all three parameters with descriptions, so the baseline is 3; the description reinforces the intended use of only_new and include_hiring ("what is new since the last check," "is anyone hiring") but does not add new technical meaning beyond the schema. It adequately aligns the parameters with the tool's purpose without compensating for any schema gap.

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: it reports "recent news and hiring movement" for known companies, with a clear scope ("several at once") and a distinguishing split between new and previously reported items. It also explicitly names sibling tools it is not (research_company, web_search), so an agent can differentiate it without inspecting other 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?

The description gives explicit when-to-use guidance: "Use for watching companies over time: what has happened at my clients, is anyone hiring, anything I should know before I reach out." It also provides exclusions and alternatives: "For one company in depth use research_company; for the open web use web_search," and it specifies scheduled-run behavior with only_new.

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 minimal readOnlyHint:false annotation, it discloses critical behavior: edges are directed, duplicate connections are idempotent (no-op rather than error), and the 'introduced' edge must use the exact spelling to be discoverable. This goes well beyond the structured fields and helps the agent anticipate side effects.

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 provides the no-op behavior and the special-case rule. It is slightly verbose in the final sentence about 'the only spelling', but all content is relevant and there is no 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?

The description gives enough context to invoke the tool correctly: what the edge means, where IDs come from, idempotency, and the introduced special case. It doesn't mention return values or error behavior for invalid IDs, but for this operation the guidance is largely complete.

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 describes each parameter, the description adds semantic detail: object_ids should come from previous create/search/list calls, connection_type is generally free-choice but has one special exact value, and the from/to directionality is reinforced with examples. This meaningfully supplements the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Connect two objects in the user's graph with a directed edge'. It names the resource (graph objects), the directionality, and gives concrete examples (file to project, person to event), which distinguishes it from node creation/deletion tools. The special 'introduced' case reinforces the specific purpose.

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 concrete usage context: use object IDs returned by create/search/list, and it specifies exactly when to use the 'introduced' edge type. It does not explicitly name sibling alternatives like disconnect_graph_objects or create_graph_object, so exclusion guidance is implicit rather than 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?

With only readOnlyHint=false in annotations, the description carries the behavioral load and does so richly: server-side verification of instruction/details/destination, the pending/executing/succeeded state machine, and the explicit instruction not to claim success for pending or queued suggestions. This is far beyond what any annotation discloses.

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, then status semantics, then authorization rule, then exclusions. Every sentence carries distinct information (state machine, auth, unsupported features) with 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 10-param write tool with no output schema, the description supplies exactly the missing pieces: result-state interpretation (pending/queued/succeeded), authorization constraints, and scope limitations. An agent has enough to call it and to report its outcome accurately.

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 70%, so the schema documents most fields. The description adds meaningful semantics for action_id (an event already extracted from the current attachment/email) and reinforces the account-review implication ('Multiple accounts require review' is in the schema). It stops short of explaining the time/day format nuances that the schema already covers.

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 and non-obvious purpose: it does not directly write an event but 'prepare[s] or queue[s] one calendar event through the shared suggestion service.' This corrects the naive reading of the name 'create_calendar_event' and implicitly distinguishes it from update_calendar_event via 'updates and cancellations are not supported here.'

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 when-to-use ('Use action_id for an event already extracted from the current attachment or email') and explicit when-not ('Attendees, RSVP, recurrence, updates and cancellations are not supported here'). The authorization rule ('Source documents never authorize a calendar write') further constrains invocation.

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 readOnlyHint=false annotation: it discloses dedup-by-type+name behavior, that the existing object is returned instead of duplicated, the exact condition for allow_duplicate, and that unknown field names are reported back with the accepted names. It also states the return shape (object with object_id).

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 dedup rule before secondary details, with no filler sentences. Dense but each clause carries distinct information; slightly long for a single paragraph.

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 parameters, a nested 'fields' object, and no output schema, the description covers the missing pieces: dedup semantics, allow_duplicate conditions, field-bag usage, and the return value. Nothing an agent needs to call 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 100%, so the baseline is 3, but the description adds real meaning: it explains the 'fields' bag with concrete per-type examples (domain_name asking_price/source, contact phone) and clarifies url usage for web_link, extending beyond the raw schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create a new object in the user's graph') and enumerates the object kinds it handles. An agent can distinguish this from siblings like connect_graph_objects, set_graph_object_fields, and list_graph_objects 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?

Gives clear triggering context ('Use when they ask to add something') and a specific exclusion for allow_duplicate ('only when the user confirms they want a second one'). It gestures at follow-up connecting via object_id but does not explicitly name the alternative tool (connect_graph_objects) for that step.

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?

Discloses significant side effects: daily execution, email digests for certain tracker types, and a web_page tracker running in 'their brain'. Also instructs the agent to always provide the returned page_url as a link. This goes well beyond the minimal 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 somewhat long and uses parenthetical examples, but it's well-organized and each sentence adds necessary clarification. Slightly verbose but not to the point of confusion.

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 four parameters, an enum, and distinct behaviors for each tracker type, the description fully equips an agent to invoke the tool correctly. It explains defaults, examples, output handling (page_url link), and the overall purpose. No missing critical context.

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 4 parameters with descriptions, and the tool description adds meaningful context: clarifies the difference between query (what to watch for) and prompt (verbatim user request with filters), explains the default tracker_type, and specifies the role of url for web_page type. This is rich additive detail.

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?

Clearly states the tool creates a tracking mechanism for standing searches, with specific examples of user requests. It distinguishes itself from sibling tools like search_linkedin_posts and search_tweets by emphasizing the persistent, ongoing nature of the tracker.

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?

Provides strong guidance on when to use the tool (when the user wants a standing search) and explains how different tracker types behave. It doesn't explicitly contrast with one-off search tools, but the examples and behavior descriptions make the intended usage 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?

Beyond the readOnlyHint=false annotation, the description discloses key behavioral traits: soft delete, data retention, restore possibility, ownership restrictions, the root user node exclusion, and the special chat behavior where it returns confirmation instructions rather than deleting directly. This is exceptionally transparent.

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: purpose, usage boundary, soft-delete semantics, parameter identification, ownership restriction, and chat-specific behavior are all covered with no redundancy. The description is dense but well-structured and front-loaded.

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 one-parameter schema and no output schema, the description provides all necessary context: what the tool does, when to use it, how to identify the target, what constraints exist, and what happens in chat. Nothing critical is missing 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% and the single parameter is documented. The description adds value by explaining that object_id can be obtained from search_graph_objects and clarifying the object ownership constraint, which helps the agent select the correct 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?

The description states a specific verb and resource ('Delete an object from the user's graph') and clearly defines scope. It distinguishes itself from related tools like purge_graph_object by explicitly noting the delete is soft and data is retained, so an agent can tell this tool apart from hard-delete alternatives.

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 when-to-use guidance: only when the user explicitly asks to delete or remove a specific object, and never as proactive cleanup. It also names how to identify the object via search_graph_objects, providing a concrete usage route.

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=false, so the description carries most of the burden and does so well: it declares the delete permanent/irreversible, warns about scale ('a synced portal can be millions of records'), and discloses the non-obvious chat behavior where the call only counts records and the user's click performs the deletion. It stops short of stating permissions or rate limits, but the safety-relevant traits are covered.

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 scope, and every subsequent sentence adds routing or safety value rather than filler. It is dense with parentheticals and runs long, which costs a point, but nothing is wasted.

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 call returns in chat (a count and a message to relay). For a bulk, permanent deletion tool the agent has the trigger conditions, the destructive implications, and the per-call constraint needed to invoke 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 adds genuine value beyond the schema: it explains the mutual exclusivity ('name one type, import or source per call') and what each mode actually removes (import_id also clears the uploaded file and the import itself; source clears the connections and the people derived from them). That is more than the enum/param descriptions alone convey.

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?

Specific verb+resource with explicit scope: 'Delete EVERY object of one type from the user's graph.' It distinguishes the sibling that deletes a single record ('Deleting one object is delete_graph_object instead') and names the three distinct modes (type, import_id, source) in a way an agent can act on 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?

Gives a concrete trigger ('delete all my HubSpot contacts') versus the single-record case, and an explicit when-not ('Use only when the user explicitly asked for these to go, never on your own initiative'). Alternatives are named rather than implied, which is exactly the routing guidance an agent 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, which is the minimum. The description adds substantial behavior beyond that: the delete is soft and reversible, objects disappear from lists/search/chat, restore_graph_objects with the returned deleted_ids undoes it, only owned objects are deleted, root user node is never deleted, and other objects come back as skipped. It also discloses the per-call ceiling (200) and the return shape (deleted_ids) even without an output schema. No contradiction with the 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?

Four sentences, no padding, each carrying distinct information: scope/limit, usage constraint, reversibility and undo path, sibling routing, ownership/root-node behavior, and environment exclusion. Front-loaded with the operation, then constraints. 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?

For a destructive multi-object mutation with no output schema, the description covers safety (soft delete, owned-only, root-node protection), reversibility (restore_graph_objects + deleted_ids), routing among the three granularity siblings, the per-call limit, and environment availability. An agent has everything it needs to call this correctly and safely.

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 fully documented in the schema. The description adds the 200 object_ids ceiling, which is a mild reinforcement of the schema's own note, but no syntax, ownership, or format details beyond it. Baseline 3 is appropriate when the schema carries the burden.

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+resource+scope: 'Delete a given list of objects from the user's graph, up to 200 object_ids in one call.' It explicitly distinguishes itself from siblings by naming delete_graph_object (single), delete_graph_objects (all of a type), and restore_graph_objects (the undo). An agent can route correctly without inspecting 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?

Provides explicit when-to-use ('only when the user explicitly asked for these particular objects to go'), when-not-to-use ('never to tidy up on your own initiative'), alternatives for other granularities (delete_graph_object for one; delete_graph_objects for every object of a type), and an environment exclusion ('Not available in the YouSpot chat'). This is about as complete as usage guidance gets.

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 discloses exactly what gets destroyed (only the single directed edge of the specified type) and what is preserved (both objects). This goes beyond the minimal readOnlyHint=false annotation and gives the agent a precise behavioral model.

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 sentences with no wasted words. The core behavior, scope, and exception are front-loaded in the first sentence, and the prerequisite is a useful second sentence.

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 deletion tool with fully documented parameters and a clear prerequisite, this is complete. It explains the action, the exact scope, the preservation of objects, and how to inspect connections before acting. No output schema is present, but none is necessary for such a focused mutation.

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 three parameters. The description reinforces the from-to direction, but adds little semantic value beyond what the input 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?

States a specific verb ('Delete') and precisely defines the resource: one edge from from_object_id to to_object_id of the given connection_type. It also clarifies it deletes only the connection, not the objects, which distinguishes it from delete_graph_object and delete_graph_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?

Gives a clear prerequisite: use get_graph_object to inspect connections and their directions first. It also implicitly tells the agent when not to use this tool by emphasizing 'nothing else; both objects stay,' though it does not explicitly name alternative tools for deleting whole objects.

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 readOnlyHint=false annotation by disclosing that the operation is destructive, not undoable, and that disconnecting a HubSpot portal deletes every synced record. This is exactly the kind of high-stakes behavioral context an agent needs before invoking a destructive 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?

Three terse sentences, each earning its place: the first states the action, the second warns of the destructive consequence, and the third gives routing guidance. The most safety-critical information is front-loaded.

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 destructive action with no output schema, the description covers purpose, side effects, when to call it, and when not to call it. An agent has everything needed to decide correctly whether and how to invoke this 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?

The input schema already documents both parameters thoroughly, including the example values and the requirement to use the exact label reported by list_integrations. The description adds a light behavioral constraint ('naming what') but does not meaningfully expand on the schema's parameter semantics, 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 names a specific verb and resource ('Disconnect one connected account') and clearly distinguishes this from related tools like list_integrations and disconnect_graph_objects. It also adds important scoping detail ('one connected account') that makes the tool's exact purpose 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?

The description explicitly says when not to call it ('Never call this to check anything') and names the alternative (list_integrations). It also states the only appropriate trigger: when the user has asked to disconnect, in their own words, naming what. This is explicit routing guidance with both positive and negative conditions.

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?

With only readOnlyHint=false in the annotations, the description carries the full burden of behavioral disclosure and excels: it states nothing is sent, watermarked drafts are refused, the user must unlock the email, and the tool reports unsupported grants. It also tells the agent what it will receive (a link to the draft).

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 core action, the critical non-sending guarantee, the unlock precondition, and the grant limitation. The description is compact yet dense with necessary information, and the most important fact (nothing is sent) appears early.

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 4 parameters and no output schema, the description covers prerequisites, failure conditions, and return value. An agent has enough information to call the tool correctly and to anticipate when it should not be called.

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 all parameters at 100%, so the baseline is 3. The description adds useful context by linking artifact_id to generate_email and by noting recipients are the ones the user named, but it does not significantly expand on the schema's parameter meanings.

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: put a generated email artifact into the user's Gmail drafts. It adds precise scope by requiring an artifact_id from generate_email and says explicitly that nothing is sent. This distinguishes it from generic draft creation tools like 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?

The description gives clear context for when the tool can be used: only for unlocked generated emails and only on mailboxes connected under a legacy modify grant. It does not explicitly mention alternatives, so it stops short of a 5, but the constraints are 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 say readOnlyHint=false; the description goes far beyond by disclosing the draft-not-post side effect, the degraded experience on older Slack installs (Copy / Open in Slack / Reconnect), and that a Send button posts 'as YouSpot' only for channels the bot is in. It also specifies the voice/formatting conventions to write in.

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?

Purpose and the crucial no-post fact are front-loaded in the first two sentences. The paragraph is dense but nearly every sentence carries distinct information; it is slightly run-on but not padded.

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 5-param tool with no output schema and minimal annotations, the description covers behavior, fallbacks, and usage triggers well. The only gap is that it never indicates what the call returns (e.g., draft confirmation or identifier), which an agent might reasonably want.

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, making 3 the baseline. The description adds modest value by clarifying to/person vs channel_id/channel routing and formatting conventions, but does not add syntax or constraints beyond the schema text.

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 Slack message for the user') and immediately draws the boundary that matters: 'Nothing posts: the draft is saved in the user's own Slack.' This cleanly separates it from the sibling send_slack_message 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?

Explicit trigger: 'Use this whenever the user asks you to write, draft or prepare a Slack message,' plus re-invoke guidance for revisions. The no-post behavior implicitly routes sending to send_slack_message, though the sibling is never named as an explicit alternative, so it falls short of a 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?

Goes well beyond the sole readOnlyHint=false annotation: it discloses that only empty fields are touched, nothing user-written is replaced, no approval is needed, the filled-fields result is returned, and batch calls fill cached data immediately while the rest is processed in the background over minutes. It also flags the daily rate limit.

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?

Purpose and the fill-only semantics are front-loaded, and the sentences are information-dense. It runs long (batch behavior, limits, per-type lookup rules), but almost every sentence earns its place, with only mild 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 mutation tool with no output schema, it covers the return ('which fields it filled'), the async batch caveat, the daily limit, and per-record-type lookup requirements. An agent has everything needed to call it correctly and 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 coverage is 100% so the baseline is 3, but the description adds real meaning: 'domain' is only for a company that has no website, and 'object_ids' is the batch alternative to 'object_id' with a 200 cap and deferred background filling. This is more than the schema restates.

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 (fill/enrich) and resource (company, contact or web link in the user's graph), and explicitly anchors it to the known 'Enrich button' behavior. It distinguishes itself from siblings like create_graph_object and set_graph_object_fields by clarifying it only fills empty fields and never overwrites user data.

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 trigger conditions ('when the user asks to enrich, fill in or flesh out a specific record'), explains the batch path (up to 200 ids in object_ids versus single object_id), and states a when-not guardrail ('do not run it across the whole graph unasked' because of the daily limit).

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 discloses cost (3 credits, charged only when saved), time (~1 minute), and the post-save review requirement ('needs the user's review'). It also warns about retries. These details go well beyond the sparse annotations (readOnlyHint=false) and give the agent a realistic expectation of side effects and resource usage.

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 dense paragraph but every sentence earns its place: action, cost, timing, usage guidance, retry warning, and return values. It's front-loaded with the primary purpose. It could be split into bullet points for readability, but it's far from 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 one-parameter tool with no output schema, the description covers all essential aspects: what it does, prerequisites, side effects (cost/time), and what it returns (brand_kit_id, open_url, source_url). Nothing an agent needs to decide whether to call it 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 describes website_url ('The website address, like acme.com.'), achieving 100% coverage. The description doesn't add further parameter-level detail, but it correctly references the parameter in context. Per the rubric, with full schema coverage the baseline of 3 applies, and there's no extra value to raise 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+resource pair: 'Read a public website and save its brand...' and lists the exact brand components (colors, fonts, radius, logo). It clearly distinguishes itself from sibling tools like create_brand_kit (manual creation) and list_brand_kits (retrieval) by framing this as an extraction-from-URL operation.

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 instructs to 'Call list_brand_kits first and reuse a matching website's kit unless the user explicitly wants another extraction' — a concrete precondition and alternative path. It also forbids retrying ('Do not call this again to retry'), which prevents an agent from looping on a failed extraction. This is exemplary usage 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 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?

Adds substantial behavior beyond the single readOnlyHint=false annotation: nothing is sent, drafts are capped at 20/day, it costs 1 credit (free on Solo/Pro), it returns the artifact id, and retries are discouraged. These are exactly the operational traits an agent needs before invoking a credentialed write.

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 purpose, then behavior, then template detail, with zero filler. It is a dense single paragraph, though, and the template enumeration is a long run-on that would scan better as a list; some sentences pack multiple distinct facts.

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 9-parameter mutation tool with nested blocks and no output schema, the description covers the return value (artifact id), cost, rate limit, template selection, body format exclusivity, and the next step. 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 coverage is only 67%, and the description compensates well: it enumerates which props each template takes (and which are required), states markdown and blocks are mutually exclusive ('never both'), documents header band/plain and align defaults, and explains that omitting brand_kit_id uses the space default. This is meaning well 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?

Opens with a specific verb+resource+scope: 'Render one branded email in a brand kit and save it to the user's files.' It distinguishes itself from siblings by stating 'Nothing is sent' and by pointing to draft_email_in_gmail as the send path, so an agent can tell it apart from send_email/create_gmail_draft 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?

Gives clear context for when to use it ('any email the user describes, from a cold intro to a follow-up to a newsletter...') and names the follow-on tool (draft_email_in_gmail) plus a retry exclusion ('Do not call this again to retry'). It does not explicitly contrast against generate_markdown/generate_pdf or state when not to use 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?

Annotations carry only readOnlyHint=false, so the description does the heavy lifting and does it well: it discloses the 1-credit cost, the return artifact (a file_id), and how that value is consumed downstream. These are concrete operational traits an agent needs before calling a metered generation 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?

Front-loaded with the core action and cost, and every clause carries signal (cost, gating, prompt guidance, exclusion, return value). It is a little dense and run-on in the middle, but not padded.

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, but the description compensates by explaining the return value and its downstream use, plus cost, size purpose, and prompt-construction guidance. For a 2-parameter generation tool this is complete enough to call 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% and the size enum is exhaustively documented, so the baseline is 3. The description nonetheless adds meaning by clarifying that size is 'the canvas it will go on' and by prescribing what the prompt should contain (scene, light, empty space for the headline), which goes beyond the schema's terse 'The scene, in a sentence or two.'

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?

Specific verb (Generate) plus resource (a photo/background to sit behind a social image), with the scope made unambiguous. It also distinguishes itself from the sibling generate_og_image by stating this output feeds that tool's background_file_id. An agent can route between the two 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 an explicit gating condition: 'Only when the user asks for a photo, picture or background.' It also states the composition intent (leave empty space for the headline) and a hard exclusion ('never ask for text, words or logos'). It stops short of naming generate_og_image as the alternative for the full composite, leaving that 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?

The description discloses important behavioral traits beyond the minimal readOnlyHint=false annotation: the document is saved to the user's files, rendered as a branded card in chat, is not a downloadable file, has no watermark or paywall, and should not be duplicated in the reply. This gives the agent an accurate model of the tool's side effects and output 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 longer than average but every sentence serves a purpose: purpose, input summary, output behavior, alternative tool, and retry guidance. The main use case and the key exclusion are front-loaded. Slightly verbose in the middle, but not padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description covers what the tool produces (a branded rendered card), where it saves the document, when to use it, when not to use it, and how to invoke it. There is no missing information an agent would need to call this 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 coverage is 100%, so the baseline is 3. The description adds value by explaining that title is optional and defaults to the first heading (also in schema), and by clarifying that brand_kit_id is what applies the user's brand. It does not add much beyond the schema for markdown itself, but the added brand context justifies a 4.

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 one document in the user's brand and save it to their files.' It enumerates concrete use cases (to-do list, checklist, plan, notes, brief, summary) and explicitly distinguishes itself from generate_pdf, so an agent can tell exactly what this tool is for.

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 says to use generate_pdf instead when the user wants a document to print, attach, or send, and frames this tool as for content the user wants to read in chat. It also gives a direct operational rule: never paste the markdown into the reply as well, and do not call 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=false, so the description carries the burden and does so well: credit/plan pricing, a 20/day draft cap, retry prohibition, default brand kit behavior, required title, and per-template prop contracts. This is well beyond what the structured fields disclose.

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 important cost/limit info, but the single dense paragraph repeats the entire eight-value size enum verbatim from the schema, which is wasted space in a description that is already long.

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 9-parameter mutation tool with no output schema, it covers cost, limits, template prop contracts, required fields, and the return value ('Returns the artifact id'). Minor parameters (appearance, gradient, align, saved_template_id) are only in the schema, but the overall coverage is solid.

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 78% and the description adds genuine meaning: it maps template_id values to their required props (simple/blog/image) and explains that props are free-text strings the agent must author itself. It partly duplicates the schema's size enum text, and align/gradient/appearance/saved_template_id are left to the schema, capping it below 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 ('Render one branded image in a brand kit') and enumerates the concrete artifacts produced (link preview card, social post, story, cover photo, etc.), which clearly separates it from siblings like generate_image_background, generate_pdf and generate_markdown.

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 cost context (1 credit, free on Solo/Pro), the 20-per-day draft limit, and an explicit negative rule ('Do not call this again to retry'), plus routing to generate_image_background for the photo and list_brand_kits for brand_kit_id. It lacks explicit when-not-to-use routing versus other generation siblings, but the context is strong.

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, so the description carries the real burden and does it well: 20 drafts/day cap, 1 credit (free on Solo/Pro), default brand kit behavior, and the artifact id + page count return. It stops short of stating auth requirements or whether drafts are queued vs synchronous.

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 is informative and the scoping/cost facts are front-loaded, but the template enumeration compresses into a single dense paragraph that is hard to scan. Slightly more structure would improve it without adding length.

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 mutation tool with no output schema, the description covers the template contract, body-format rules, defaults, cost, rate limits, and return values. An agent has everything needed to construct a valid call without further 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 82%, but the description adds substantial meaning beyond it: per-template line-item fields and their 30-item cap, that all line-item fields are strings, the YYYY-MM-DD date rule, the 'markdown or blocks, never both' exclusive-usage rule, and how the first heading becomes the title unless title is passed.

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 ('Render one branded PDF in a brand kit and save it to the user's files') and enumerates the concrete document types it covers. It clearly separates itself from siblings like generate_markdown and generate_image_background by naming the branded-PDF artifact and its templates.

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 routing for each template ('invoice' takes items..., 'report' takes markdown or blocks...) plus fallback guidance for unfamiliar asks ('a press release... is still a report, letter or proposal'). It also adds a hard exclusion – 'Do not call this again to retry' – and states the daily limit and cost.

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, so the description carries some burden. It usefully discloses that saved_template_id values are replaced, that views are free (no watermark/unlock), and that it returns artifact_id. However it omits what 'live data' implies operationally, whether saved views can later be updated/deleted, and any auth or quota 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?

Front-loads the core action and definition, then compactly covers the key param behavior and return value in two sentences. Every clause earns its place 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 mutation tool with 5 optional params, no output schema, and a nested 'state' object, the description is strong: it defines the artifact, return value, and saved_template_id override behavior. It could better distinguish from update_view/save_as_template and mention validation of spec_version, but it's close to complete.

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 baseline is 3. Description adds marginal value by clarifying saved_template_id semantics ('anything you pass replaces its value') but does not explain source syntax, spec_version format, or state keyed-by-name 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?

States a specific verb+resource ('Save a view') and elaborates what a view is with concrete examples (dashboard, Markdown document, feed of posts). Clearly distinguishes from siblings like update_view (mutation of existing view) and generate_markdown through the 'view language renders with live data' framing.

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?

Implies usage via 'a view the user wants to keep' but never explicitly states when to use this versus save_as_template, update_view, or generate_markdown. The saved_template_id sentence gives some context ('starts from a view template saved earlier') but no clear when/when-not guidance or alternative 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 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 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.

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond that: the tool returns not only the requested object but also its connected objects/edges, and it supports lookup by either object_id or name. This gives the agent a clear expectation of what the call will return.

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 core behavior and return value are front-loaded, and the usage guidance follows naturally. 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?

For a simple read tool with two optional parameters and no output schema, the description provides enough context: what it retrieves, how to identify the object, and when to use it. A slightly more explicit note about ambiguous name matches or missing objects would push it to 5, but this is adequate for confident 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 both parameters are documented in the schema. The description adds meaningful semantics on top: object_id is exact and preferred, and search/list return it; name can be full or partial. This helps the agent choose the right parameter and understand matching 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?

The description clearly states the action ('Get one object'), the resource ('user's graph'), and the distinguishing feature (returns connected objects/edges). It names concrete examples (person's spaces, note's subject), which makes the tool's role unmistakable and differentiates it from searching or listing graph 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?

The description explicitly tells the agent when to use this tool: when the user asks about a specific thing in their graph, or when following a connection found on another object. It does not explicitly say when not to use alternatives like search_graph_objects or list_graph_objects, but the 'specific thing' guidance strongly implies the distinction.

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 already establishes the safety profile, and the description adds genuine behavior beyond it: the default bounded 30-day window, the portal-selection rule, the instruction to cite returned record URLs, and a caveat that partial history does not imply an overdue task. Return format and pagination remain undisclosed.

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 before routing and constraints, and each sentence adds a distinct piece of information (usage, portal rule, default window, citation, interpretation caveat). Slightly dense but no wasted sentences.

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 only a readOnlyHint, 5 undocumented parameters, and no output schema, the description does most of the work: defaults, portal selection, contact-scoped lookup, and output citation are all covered. The gap is that kind/limit semantics and return shape are never addressed, so it is not fully self-sufficient.

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 0% across 5 parameters, so the description carries the full burden. It meaningfully explains days (default 30-day window), portal_id (one portal when several are connected), and contact_id (later activity for a specific person), but says nothing about kind or limit, leaving two parameters undocumented.

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 (recorded notes, emails, calls, meetings, tasks in the user's connected HubSpot portal), which clearly separates it from ask_about_hubspot_* and get_hubspot_summary. It never explicitly contrasts with the closest sibling search_hubspot_crm, so an agent must infer the boundary.

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 usage context ("for follow-ups, explicit next steps, and supporting activity") and a prerequisite ("Select one portal when several are connected"). There is no when-not-to-use guidance or named alternative, so it stops short of a full routing statement.

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 read-only nature is covered. The description adds meaningful behavioral context beyond that: it clarifies the tool returns a summary/overview of synced data, not live or unsynced data, and that it can serve as a data-availability check. No contradictions 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?

Three sentences with no filler. The core output description is front-loaded, followed by targeted use cases and explicit sibling routing. Every sentence 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 the zero-parameter, read-only, simple-summary nature, the description fully explains what the tool returns, when to use it, and which sibling tools handle adjacent cases. No output schema exists, but the description substitutes for it by naming the exact summary fields. 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 tool has zero parameters, so the baseline is 4. The description correctly focuses on what the tool returns rather than parameter details, and no parameter clarification 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?

Description states a specific verb ('Overview') and resource (synced HubSpot data) and enumerates exactly what it covers: portals, contact/company counts per portal, and last sync times. It also explicitly distinguishes itself from sibling tools ask_about_hubspot_contacts and ask_about_hubspot_companies, making the intended scope 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?

Gives explicit use cases: questions about how much HubSpot data exists, which portals are connected, whether data is up to date, and pre-checking data before promising an answer. It also names the alternative tools for record-level questions, providing clear when-to-use versus when-not-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?

Beyond the readOnlyHint annotation, the description discloses crucial behavioral context: the URL only starts the connection process, nothing is connected by calling the tool, and the agent must never claim a connection was made because only the user can grant it in their browser. This is valuable and accurate.

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 cover purpose, usage context, and a behavioral caveat without redundancy. The content is front-loaded and each sentence adds necessary guidance.

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, read-only tool with no output schema, this description is complete. It explains what the tool does, when to use it, when not to use it, and the critical limitation about not claiming a connection. 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 input schema already provides 100% coverage for the single 'key' parameter, so the description need not repeat schema details. The description adds minimal semantic context by noting the URL is for one integration, but it does not meaningfully expand on the parameter 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 it returns a URL that starts connecting an integration, which is a clear and specific purpose. It also distinguishes itself from the chat card by explicitly saying to show the integrations_list card instead when in chat.

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 names when to use this tool: for surfaces that cannot render a card, such as Slack, SMS, and email. It also directs the agent to use the integrations_list card in chat, providing a clear alternative and exclusion condition.

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 already declares the safety profile, but the description adds meaningful behavior beyond annotations: the data source (imported LinkedIn export), the ordering (oldest first), the returned fields (who sent each message plus full text), and the ambiguity fallback (returns candidates to choose from when a name matches several people). It does not mention pagination or result-size behavior, keeping it below 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-loaded with the core action, then usage examples, then the argument and ambiguity note. Each sentence earns its place, though the example-heavy middle sentence is slightly dense and could be trimmed.

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, yet the description usefully previews the return contents (per-message sender and full text) and the disambiguation behavior, which is what an agent needs. Missing only edge-case handling like what happens when no conversation exists or how limit interacts with the oldest-first ordering.

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 (person, limit) are already documented in the schema. The description restates 'Pass a name or a LinkedIn profile URL' and the ambiguous-name behavior but adds no syntax or format detail beyond the schema. 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+resource ('Read the user's LinkedIn message history (DMs) with one person') and adds scope (one person, imported export), ordering (oldest first), and contents (sender + full text). An agent can distinguish this from search_linkedin_messages, which is query-based rather than thread-based, 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 concrete usage contexts ('what did I message Sander?', 'did she ever reply?', 'before drafting a follow-up'), which is clear when-to-use guidance. It stops short of naming when NOT to use it or pointing at the obvious alternative search_linkedin_messages, so it is 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?

With only readOnlyHint=true in annotations, the description carries the behavioral burden and does so richly: it enumerates returned fields (name, headline, profile_url, followers or null when unknown), notes replies are nested under each comment, and explains the truncated/comment_count semantics. It even discloses that comments render as a sortable table in chat, which is non-obvious 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?

Front-loaded with the resource and its scope, then usage, then input handling, then output/summary behavior — a sensible order. It runs long and blends agent response-formatting guidance (themes, sentiment, disagreement) into the tool description, which costs a point on tightness.

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, so the description must describe returns — and it does, covering comment fields, nested replies, and the truncation signal. Nothing needed to call it correctly or interpret its results 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 baseline is 3, but the description adds real value beyond the schema: 'Pass the link exactly as given; feed/update links, share links and bare activity ids all work,' clarifying accepted input formats and that no normalization 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?

States a specific verb and resource (fetch every comment on one LinkedIn post) and immediately scopes it: 'Works for any public post, not only the user's own,' which separates it from get_my_linkedin_posts and search_linkedin_posts. An agent can pick this tool 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?

Gives concrete trigger conditions ('when they paste a LinkedIn post link and ask what people are saying, for a summary of the comments, or who commented'), which is clear usage context. It stops short of naming an explicit alternative or a when-not-to-use condition, so it lands just under the top band.

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 returns an overview/aggregate summary rather than individual messages, covers only imported LinkedIn data, and includes date-range and sent/received dimensions. This goes beyond what the annotation alone 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?

Two sentences, front-loaded with the core value and then concrete use cases. Every sentence contributes useful information without repetition or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.