YouSpot

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?

The description goes beyond the readOnlyHint annotation by explaining the data returned and the conditional behavior when comments_synced is false. It also tells the agent how to handle that case, which is useful behavioral context. It doesn't mention edge cases like pagination or rate limits, but the disclosed behavior is solid for a read-only analysis tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat long but each sentence earns its place: it defines the output, gives usage context, tells the agent what to cover from the data, and handles a conditional sync state. It is well-structured and front-loaded with the core purpose.

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 compensates well by enumerating the returned data (per-post stats, comment samples, headlines) and by explaining how to handle the comments_synced=false state. For a single-parameter read-only tool, the description provides everything an agent needs to call and interpret 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% for the single post_count parameter, which already documents default and max values. The description does not add additional meaning about the parameter, so a baseline score 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 identifies the tool as an engagement analysis of recent LinkedIn posts, specifying the returned data: per-post stats, comment samples, and headlines. It is distinct from sibling tools like get_my_linkedin_posts or search_linkedin_posts by focusing on analysis rather than retrieval, though it does not explicitly name or contrast with those 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?

The description explicitly states when to use the tool: 'Use when they ask for an analysis of their recent posts, what people are saying about them, or who their audience is.' It also gives conditional guidance for comments_synced=false. However, it does not describe when not to use it or explicitly point to alternative 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?

The readOnlyHint is false, and the description goes well beyond that by explaining the exact side effect (moves out of inbox, stays in All Mail), recoverability, the legacy-grant requirement, and that the tool itself will report when the mailbox cannot be changed. This fully discloses 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?

Three sentences, each earning its place: core outcome, usage/confirmation rule, and connection constraint. The most decision-relevant information is front-loaded, and there is no repetition of schema or annotation content.

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

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

For a single-message, two-parameter tool with no output schema, the description covers the operation's effect, recoverability, when to use it, the required permission condition, and expected failure mode. Nothing an agent needs to invoke it correctly or decide whether to suggest 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?

Schema description coverage is 100%, so the baseline of 3 applies; the schema already documents message_id and account. The description adds a clarifying 'one Gmail message' but does not meaningfully enrich the parameter-level semantics 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 states a specific verb ('Archive') and resource ('one Gmail message'), then clarifies the exact outcome: it leaves the inbox but stays in All Mail and is fully recoverable. This clearly distinguishes it from deletion, sending, or other Gmail-related 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?

Explicitly says to use it 'only when the user asked for the archive' and to confirm first if it is the agent's own suggestion. It also warns that it only works on legacy modify-grant mailboxes and that current read-only connections cannot change the mailbox, giving clear when-to-use and 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?

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?

The readOnly annotation already covers safety, and the description adds some behavioral context by listing what is audited and instructing the agent not to write findings as a table. However, 'Emit the card it names and let the reader decide group by group' is cryptic and does not clearly disclose the actual return 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 a dense, run-on list using vague metaphors like 'clogging up the user's brain' and 'card it names'. It mixes audit categories with output instructions in one unstructured paragraph, making it harder to parse than a crisp, scannable definition would be.

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

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

For a no-parameter read-only tool with annotations, the description covers the audit categories, but the output format is underspecified: 'Emit the card it names' does not tell an agent what card, what shape, or what fields the response will contain. The lack of an output schema makes this gap more significant.

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 has zero parameters and schema coverage is 100%, so the description is not required to explain parameter meanings. The baseline of 4 applies because there is nothing for the description to add.

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 an action ('audit') and enumerates what it examines: object counts, machine logs, duplicate people/records/documents. However, the resource ('the brain') and the output ('the card it names') are metaphorical and ambiguous, so an agent would struggle to know exactly what result to produce.

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

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

There is no guidance on when to use this tool versus siblings like what_needs_attention or get_connections_summary. The description does say 'Reads only' and gives an output instruction, but it never states the triggering condition or distinguishes this audit from other analysis 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?

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 provide readOnlyHint=false, which is minimal. The description adds valuable behavioral context: the first call records a baseline and reports no change, snapshots are kept per page and tag, and two watchers on the same page do not consume each other's changes. It does not detail the diff format or how often checks can be made, but it covers the most important behavioral surprises.

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 core function is in the first sentence, followed by use cases, then the baseline caveat, then the tag guidance, then sibling routing. Every sentence earns its place 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?

For a tool with only 2 parameters, no output schema, and minimal annotations, the description covers the key context: what it does, when to use it, the baseline behavior, the tag semantics, and alternatives. It could mention what the diff looks like or whether the tool can be used on non-public pages, but these are minor gaps given the tool's simplicity.

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 both parameters well. The description adds meaning by explaining why the tag matters ('so two watchers on the same page do not consume each other's changes') and by framing the url as a public web page. This goes beyond the schema's field-level 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 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 immediately distinguishes it from siblings like read_web_page and web_search. It also names the sibling it is not, which makes the tool's purpose 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 explicitly says when to use this tool ('Use for watching one page over time') and names alternatives with their conditions ('For the contents of a page use read_web_page; for the open web use web_search'). It also explains the first-call baseline behavior and the tag requirement, which are essential usage details.

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 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?

Beyond the readOnlyHint=false annotation, the description adds meaningful behavior: omitted colors/fonts/radius default to the YouSpot kit, logos are not handled here, and the tool returns a brand_kit_id. These are real side-effect and return-value disclosures that help the agent predict consequences. Not exhaustive (e.g., no mention of overwriting or creation semantics), but solid.

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 tight sentences, each purposeful: the action and scope, required/default behavior, logo caveat, alternative routing, and return value. No fluff, and the most decision-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?

Given 7 parameters, nested objects, and no output schema, the description covers the core essentials: creation scope, required field, defaults, logo handling, sibling alternative, and the returned brand_kit_id. It could additionally explain what happens to the active space or how dark_mode/documents defaults behave, but the schema already carries the documents purpose, so this is 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 71%, and the description adds value by explaining the default behavior for omitted colors, fonts, and radius ('start from the YouSpot kit') and reinforcing that only name is required. This bridges a gap the schema alone does not fill. It doesn't clarify dark_mode or the fonts object structure further, but the enum values and other schema descriptions cover those reasonably.

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

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

States a specific verb and resource: 'Create a brand kit by hand' in the user's active space. It distinguishes the scope clearly from the sibling extract_brand_kit, and also adds boundaries like logos being uploaded separately. The agent knows exactly what this tool does and what it does not do.

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 to the alternative: 'To import a brand from a website use extract_brand_kit instead.' The phrase 'by hand' and 'from what the user gave' establishes when this tool is appropriate versus the import path. No inference needed.

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 only readOnlyHint=false, so the description carries the real burden and delivers: the queue/deferred nature of the write, server-side verification of instruction/details/destination, and a full status lifecycle (pending=review or missing details, executing=queued, succeeded=added). The instruction not to claim success for pending/queued states is unusually valuable behavioral guidance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action, then layers constraints, status semantics and exclusions in a compact sequence of short declarative sentences. Dense but every sentence carries a distinct, actionable constraint 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?

Although there is no output schema, the description substitutes by explaining the return/status states (pending/executing/succeeded) and what each means, plus the verification behavior. For a mutation-adjacent tool dependent on a suggestion service, this is sufficiently complete 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 description coverage is 70% across 10 parameters, so the schema already documents most fields. The description adds genuine meaning for action_id (an event extracted from the current attachment or email) and account (multiple accounts require review), but leaves start/end/timezone/all_day/location/description entirely to the schema. Marginal added value over structured fields, appropriate at baseline 3.

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

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

States a specific verb and resource (create one calendar event) but goes further by clarifying it operates through a shared suggestion/queue service rather than writing directly. It distinguishes itself from update_calendar_event by explicitly naming unsupported operations (updates, cancellations, recurrence, attendees). An agent can place this tool precisely without opening a schema.

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

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

Explicitly states when to use action_id (an event already extracted from the current attachment or email) and an important boundary ('source documents never authorize a calendar write'). It also enumerates what is out of scope (attendees, RSVP, recurrence, updates, cancellations), steering the agent to siblings. Nothing material 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 goes well beyond the minimal readOnlyHint=false annotation. It discloses that nothing is sent, the draft lands in Gmail's Drafts folder, the body must be plain text, current read-only connections cannot create drafts, and the tool will indicate failure if the grant is absent. 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 somewhat long but every sentence earns its place: core behavior, non-sending guarantee, content guidelines, usage routing, and a permission caveat. It is front-loaded with the essential action and only slightly dense in the middle.

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 create-draft tool with sparse annotations and no output schema, the description covers the essential operating context: what the draft is, where it goes, what to write, when to use the tool, and the grant limitation. An agent has enough information to invoke it correctly and to anticipate failure.

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 parameters are already fully documented. The description reinforces the body format ('plain-text body (no HTML or markdown)') and the 'in the user's voice' guidance, but it does not add substantial meaning beyond what the schema already 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 states a specific verb and resource: 'Create a DRAFT email in the user's connected Gmail mailbox' and clarifies that nothing is sent, distinguishing it from send_email. However, it does not differentiate from the closely named sibling draft_email_in_gmail, which weakens the distinction among 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 states when to use the tool ('Use this whenever the user wants an email written to someone else') and contrasts it with send_email ('remains only for mailing the user their own address'). It also flags the legacy modify grant restriction, which is important context for when the tool will fail.

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 reveals an important upsert behavior: if an object of the same type and name already exists, it is returned instead of duplicated. It also explains when allow_duplicate should be true and states that the return value includes object_id for follow-up connecting, which is useful in the absence of an output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Each of the four sentences serves a distinct purpose: stating the core action, giving the usage trigger with examples, explaining dedup/allow_duplicate behavior, and describing the return value. There is no redundant filler or repetition of schema content, and the most important scoping 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?

Given there is no output schema, the description's note that the tool returns the object with its object_id is essential and covers the key return contract. It also addresses deduplication, the allowed object types, and the allow_duplicate edge case, while the schema handles field-level details. For a create tool of this complexity, 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?

Since schema description coverage is 100%, the schema already documents all seven parameters, setting the baseline at 3. The description adds meaningful semantics for allow_duplicate ('only when the user confirms they want a second one') and for the dedup condition tied to type and name, which helps an agent decide parameter values beyond the schema 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 states a specific verb ('Create') and a specific resource ('object in the user's graph'), then enumerates the kinds of objects it covers (project, note, fact, web link, etc.). This clearly distinguishes it from sibling create_* tools like create_calendar_event, create_gmail_draft, and create_tracker, which target different resource 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?

The description explicitly says 'Use when they ask to add something' and lists the supported object types, giving a clear trigger for invocation. It also provides conditional guidance for allow_duplicate, but it does not explicitly name sibling alternatives such as search_graph_objects for finding existing objects, so it stops short of full 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?

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?

The description discloses that deletion is permanent, that the scale can be millions of records, and crucially that the tool does not delete in chat but returns instructions for a confirmation card that the user must click. These behaviors go well beyond the sparse annotations and help the agent set correct expectations.

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 but every sentence earns its place: purpose, alternative, permanence/scale, explicit-consent rule, cardinality, and chat confirmation behavior. The key distinction is front-loaded and the sentence order supports fast decision-making.

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 dangerous bulk-delete tool with one parameter and no output schema, the description covers what is deleted, when it is appropriate, its permanence, how the confirmation flow works in chat, and the constraints on the parameter. There is no significant missing context that would cause an agent to misuse it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the schema already documents object_type well, but the description adds the important cardinality constraint of naming exactly one type per call and gives a concrete example. It also points to search_graph_objects and type counts as sources for valid types, adding useful context 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 leads with a specific verb and resource: delete every object of one type from the user's graph. It explains the bulk category-clearing use case with an example and explicitly contrasts it with delete_graph_object for single-record deletion, distinguishing it from the most similar sibling.

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 states exactly when to use the tool (user asks for an entire category to go), when not to (single object → delete_graph_object), and adds constraints: only after explicit request, one type per call, and that in chat it only schedules deletion via a confirmation card. This is explicit guidance an agent can act on directly.

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?

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 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?

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?

Beyond the readOnlyHint=false annotation, the description discloses consequential behavior: saves to the user's files, sends nothing, has a 20-draft daily limit, applies a watermark until unlocked, refuses Gmail drafting until cleanup, returns an artifact id, and instructs no retries. This is exceptionally transparent for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but the length is earned by the template-by-template parameter breakdown and behavioral constraints. It is front-loaded with purpose and proceeds logically through usage, parameters, and next steps; only the template list feels slightly dense, but it is organized and necessary.

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

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

Given the tool's complexity, nine parameters, nested blocks, and no output schema, the description leaves almost nothing missing: behavior, rate limits, required props, body format constraints, header/align options, default brand behavior, watermark/unlock flow, return value, and downstream tool call are all covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 67% schema description coverage, the description compensates thoroughly: it enumerates every template's accepted props and marks required fields, explains markdown vs blocks, and defines header/align values and brand_kit_id fallback behavior. This adds substantial meaning beyond the bare input 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 opens with a specific verb and resource: "Render one free branded email draft in a brand kit and save it to the user's files." It also differentiates itself from siblings by stating "Nothing is sent" and explicitly routes later work to draft_email_in_gmail, so an agent can distinguish it from send_email, create_gmail_draft, and save_as_template.

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 and when-not-to-use guidance: use it for any described email, do not use it to retry ("Do not call this again to retry"), and use draft_email_in_gmail once the draft is unlocked. It also gives concrete configuration guidance such as "Leave brand_kit_id out to use the space's default brand."

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?

The description goes far beyond the readOnlyHint:false annotation by disclosing the watermark, the 20-per-day draft limit, the one-credit unlock flow, the 'you cannot unlock it' restriction, persistence to the user's files, and the returned artifact id. It also warns against retrying, which is exactly the kind of behavioral nuance 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?

The description is dense and front-loaded with the most important behavior, and every sentence adds operational guidance. It loses a point because the size list largely duplicates the schema's parameter descriptions, and some of that repetition could have been trimmed while preserving the unique behavioral warnings.

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 tool with 8 parameters, a nested props object, and no output schema, the description is remarkably complete: it specifies required fields, template-specific inputs, defaults, return value, and failure/retry policy. The remaining parameter details (align, gradient, appearance, saved_template_id) are already documented in the schema, so 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?

Although schema coverage is already 75%, the description adds crucial semantics: template_id 'simple' and 'blog' each have specific props keys, title is required, and 'Leave brand_kit_id out to use the space's default brand.' It also reinforces size options with contextual placement details, giving the agent everything needed to construct valid 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?

The description uses a specific verb-resource pair ('Render one free branded image draft...') and clearly distinguishes this from siblings by covering image generation for social/link previews while siblings like generate_pdf, generate_email, and generate_substack_post target other output types. It also enumerates the exact output formats, making the tool's scope 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 gives strong context on when to use it (every size is tied to a posting destination), and it adds direct behavioral instructions like 'Do not call this again to retry.' It does not explicitly name alternative tools for other content types, but the context is clear enough for an agent to select this tool for image drafts.

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 provided by annotations, the description carries the full burden of behavioral disclosure, and it does so richly: drafts are limited to 20/day, the PDF carries a watermark until unlocked, the agent cannot unlock it, the first heading becomes the title, markdown and blocks should not both be used, and the call returns artifact id and page count. The 'do not call this again to retry' instruction adds important operational 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 long but dense and front-loaded with core purpose before template details. Every sentence adds useful operational guidance, and the template summaries are efficient. It could be slightly better structured with line breaks or bullets, but it avoids fluff and 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 high complexity (11 parameters, nested objects, 5 templates, no output schema, sparse annotations), the description covers what an agent needs: template selection, payload shape, constraints, defaults, return value, rate limit, watermark behavior, and a retry warning. The few parameters not explicitly covered (page, footer_text, page_numbers, saved_template_id) are already documented in the schema, so 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?

Schema coverage is 82%, so the baseline is 3, but the description adds substantial meaning beyond the schema: it explains which props and items each template expects, states that line item fields are strings and dates are YYYY-MM-DD, clarifies markdown-vs-blocks exclusivity, and explains brand_kit_id defaulting. This goes well beyond the schema's generic property 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 opens with a specific verb and resource: 'Render one free branded PDF draft in a brand kit and save it to the user's files'. It goes on to enumerate the template types (invoice, statement, report, letter, proposal), which clearly distinguishes this from sibling tools like generate_og_image or generate_email. An agent can immediately tell this is for producing document PDFs, not other content.

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 clearly states what kinds of documents are appropriate ('any document the user describes, from an invoice... to a report') and covers all five template options plus fallback guidance for unfamiliar asks. It does not, however, explicitly name sibling alternatives or state when not to use this tool, so it falls just 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?

Annotation Contradiction: annotations declare readOnlyHint=true, but the description says the tool saves the draft to the user's files, enforces a 20-per-day draft limit, and blocks copying until an unlock. These are stateful side effects, so the read-only annotation is directly contradicted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the key safety guarantee. Every sentence adds operational value, and the density is warranted by the tool's complexity, though light structure would make the many constraints easier to scan.

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 templates, body format, audience, daily limit, credit gating, and retry prohibition. The main gap is that, with no output schema, it never describes what the tool returns or how to locate the saved draft afterward.

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?

Adds meaningful detail beyond the schema: template_id is tied to expected props ('post' takes signoff; 'digest' takes intro, signoff), title/subtitle roles are clarified, and markdown versus blocks is stated as mutually exclusive. The audience line mostly repeats the schema enum, so it is strong but not maximal.

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

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

States a specific verb and resource: draft one Substack post and save it to the user's files. It also clarifies the non-publishing, non-sending scope, which distinguishes it from email draft tools and publishing-related siblings.

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

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

Gives clear usage context: template-specific props, markdown-or-blocks exclusivity, audience values, and an explicit 'do not call this again to retry' instruction. It does not name sibling alternatives or provide when-not-to-use rules, so it stops 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?

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. The description adds rich behavioral context: ordered by start time, default range behavior, RFC3339 format with example, count_only sweeping up to 12,500 events, calendar_id resolution, and account-connectivity error handling with a specific link. 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?

Every sentence earns its place. The main purpose is front-loaded, followed by logical scenarios (time range, query, count_only, calendar_id, error handling). No redundancy or fluff despite the density of information.

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

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

For a 7-parameter, no-output-schema tool with no required params, this description is exceptionally complete. It specifies the return fields, explains all parameters in context, covers edge cases (past ranges, named calendars, count_only), and handles error scenarios. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are already documented. But the description adds substantial value beyond the schema: explains time_min/time_max roles with an example, notes time_min defaults to now when time_max omitted, clarifies count_only behavior vs listing, and mentions calendar_id comes from list_google_calendars. This enriches the baseline meaning.

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: "List events from the user's connected Google Calendar, ordered by start time" and enumerates the fields returned (summary, start/end, location, organizer, attendees, meeting link). This clearly distinguishes it from siblings like create_calendar_event, update_calendar_event, and list_google_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?

Provides explicit guidance: default behavior (upcoming from now), how to handle "what's on my calendar tomorrow" with time_min/time_max, when to use count_only for long-range "how many" questions, and how to read a named calendar via list_google_calendars. It also instructs the agent on error handling (show message and link for no account).

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?

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?

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.

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

For a zero-parameter, read-only summary tool with no output schema, the description is complete: it enumerates the exact dimensions of the summary (message count, conversation count, date range, sent/received) and gives example queries. An agent can confidently decide to use it and predict the response shape.

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 are zero parameters and schema description coverage is 100%, so there is no parameter documentation burden on the description. The description still usefully implies the tool operates over the full imported message history without requiring arguments.

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 (the user's imported LinkedIn messages/DMs) and the specific purpose: producing a high-level summary with counts, conversation count, date range, and sent/received breakdown. This is distinct from siblings like top_message_correspondents or get_connections_summary because it focuses on aggregate shape of LinkedIn message history.

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 when to use the tool: for 'how many messages do I have?' and questions about the shape of message history. It does not explicitly list when not to use it or name alternatives, but the provided use cases are concrete enough to guide an agent.

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 goes well beyond that: it discloses newest-first ordering, that author_counts spans ALL bookmarks, the daily sync cadence, the account-reconnect failure mode, and that the result carries a link. No contradiction with the read-only 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 deliver return content, rollup semantics, sync context, parameter guidance, and troubleshooting with zero fluff. The most decision-relevant facts (what it returns and how it is ordered) are 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?

With no output schema, the description compensates by enumerating returned fields (author, text, date, engagement, link), explaining the special author_counts rollup, and covering the sync failure path. It is complete enough 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 description coverage is 100%, and the schema already documents limit's default/max, query's case-insensitive substring behavior, and author's @handle filtering. The description's line 'query filters bookmark text, author narrows to one @handle' largely restates 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+resource ('posts the user bookmarked on X') and adds distinctive details like newest-first ordering and the author_counts rollup. This clearly differentiates it from siblings such as get_my_tweets and search_tweets without needing to open their 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 frames when to reach for it ('use it directly for questions like whose posts do I bookmark most?') and notes the daily-sync prerequisite. It does not name sibling alternatives or state when not to use it, so it stops short of a full 5.

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

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

Annotations carry only readOnlyHint=true, so the description does the heavy lifting — and it does it thoroughly: response invariants (total_posts_stored always included), pagination contract (has_more → next_offset → offset), field semantics (like_count is thumbs-up alone vs total_reaction_count is all types), and default ordering behavior. No contradiction with readOnlyHint since this is clearly a fetch operation.

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?

Long but information-dense — every sentence earns its place (routing, examples, field meanings, pagination). Slight redundancy in restating sort='top' ('their best-performing with sort=top' then 'sort=top is what answers...') but that repetition serves a routing purpose. Core purpose is front-loaded before alternatives and edge details.

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 list tool with no output schema, the description fully covers the agent contract: row content, engagement field meanings, sort semantics, response invariants (total_posts_stored, has_more, next_offset), and pagination. An agent can select, sort, and page through results without ambiguity; nothing needed 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 coverage is 100%, so baseline 3 applies. The description adds real value on top: it maps sort='top' to natural-language queries ('my best posts', 'what performed well'), clarifies when sort='oldest' is the right choice (start of posting history), and explains the offset paging contract (call again with offset set to next_offset). This exceeds baseline but the schema already documents the enum and each parameter well.

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 ('The user's own LinkedIn posts') plus what's included (engagement numbers: reactions, likes, comments, shares). Explicitly contrasts itself with the closest sibling, linkedin_analytics, and is clearly distinct from get_my_tweets (platform-specific). An agent can tell exactly what this tool returns and how it differs from similar ones.

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 traffic: 'Answer those from here rather than from linkedin_analytics, which needs an OAuth grant this user may not have given.' Gives concrete query phrasings that should be answered here ('my top 10 posts', 'what did I post last week?', 'how many posts do I have?') and instructs the agent to compute averages and comparisons from returned rows. Also states the exclusion condition (OAuth grant) with reasoning.

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 beyond the readOnlyHint annotation by explaining that the tool returns an 'upgrade_plan value' that a card consumes, and that the card performs the purchase. This prevents the agent from falsely reporting a completed transaction and discloses the tool's read-only nature without contradicting 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?

The description is two sentences, front-loads the core purpose, and every sentence earns its place. It packs usage timing, output contents, and a critical behavioral warning without 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 parameterless, read-only tool with no output schema, the description supplies all necessary context: what data is returned, when to invoke it, and how to interpret the response. 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 schema already provides complete coverage (100%). The description adds no unnecessary parameter details; the baseline of 4 is appropriate for a parameterless tool where schema coverage is complete.

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 returns the user's current YouSpot plan, credit balance, and upgrade options. It also adds precise domain context (pricing, plans, upgrading, credits, limits) that distinguishes it from unrelated 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?

It explicitly instructs when to call the tool: 'Call it before answering anything about pricing, plans, upgrading, credits or limits'. It also provides a behavioral directive about not implying a payment happened, leaving no ambiguity about how to handle the result.

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 covers the safety profile, and the description adds useful behavioral context: it reads a synced archive (hence fast but potentially stale), returns newest-first ordering, and may surface a connection link when no account is connected. 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?

Three sentences with no filler. The output scope is front-loaded, the staleness caveat is placed second, and the query/error-handling behavior is stated last. Every sentence contributes useful information.

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

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

For a zero-required-parameter read tool with no output schema, the description covers what is returned, ordering, filtering, the sync caveat, and the no-account fallback behavior. An agent has enough to decide when to call it and what to do with the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents limit, query, and handle fully. The description re-states that query filters tweet text, but adds no new meaning beyond the parameter names and schema 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?

States a specific resource ('the user's own tweets'), a clear verb ('get'), and precise characteristics (newest first, from connected X accounts, includes text, metrics, date, link). This differentiates it from siblings like search_tweets (which searches external tweets) and get_my_linkedin_posts (a different platform).

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 clear context: this reads the user's own connected-account tweets, not general tweets, and warns that a brand-new connection may not have synced yet. It includes an error-handling instruction for the no-account-connected case, but does not explicitly name alternatives 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?

The readOnlyHint annotation already signals safety, and the description adds meaningful behavioral context: it discloses exactly what is returned, including linked notes and backlinks, not just raw file content. Although it does not mention potential edge cases like missing vaults or permission failures, the additional content detail goes beyond the annotation and helps the agent predict 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 compact and front-loaded: the first sentence defines what the tool returns, the second explains identification, and the third gives usage guidance. Every sentence earns its place with no filler or repetition of the title beyond the opening verb. It is easy to scan and immediately 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?

There is no output schema, so the description correctly takes on the responsibility of explaining return contents, covering markdown, frontmatter, tags, linked brain objects, and backlinks. It also covers the three supported lookup methods and when to use the tool. For a read-only note retrieval tool with modest complexity, 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?

Schema description coverage is 100%, so all three parameters are already documented. The description adds a small clarification that identity can be established by object_id, path, or title, and that object_id typically comes from a search, but this mostly restates the schema's own parameter descriptions. Baseline 3 is appropriate because the schema carries the parameter documentation 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 ('Read') and a precise resource: one note from the user's Obsidian vault, in full. It clarifies the scope by enumerating exact contents (markdown, frontmatter, tags, wikilink targets, backlinks) and distinguishes itself from search_obsidian_notes by contrasting excerpt vs. full note. No ambiguity remains about what this tool does.

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 usage guidance: 'Use this whenever a search result looks like the answer' and notes that search returns an excerpt while this returns the full note. It also provides a clear workflow for following backlinks when the user asks about connections, which differentiates it from mere read-only retrieval. This is strong when-to-use guidance with a named alternative implicitly invoked.

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 valuable behavioral context beyond that: data comes from a stored 'brain' capture, channel enablement is a prerequisite, and empty results have a specific meaning and remedy. 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?

Two concise sentences with no filler. The result shape is front-loaded, and the storage caveat and empty-result behavior follow logically.

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 two-parameter read-only tool with full schema coverage, the description explains what is returned, the ordering, the storage scope, and the meaning of an empty result. 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?

Input schema coverage is 100%, so both parameters are already documented. The description does not add any extra parameter-level detail, 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 clearly names the resource (a single Slack thread) and what it returns (the parent and every reply, oldest first). It also distinguishes from sibling search/list tools by emphasizing 'one Slack thread' from the stored messages.

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 provides strong contextual guidance: this reads only captured threads and an empty result means the channel was not enabled, with a concrete fix. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent.

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, but the description adds valuable behavioral context: it reads from a synced graph (potentially stale), mentions total_followed as the synced total, and explains the no-account-connected scenario (returning a link). These go beyond the annotation and help the agent understand real-world 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 three sentences, front-loaded with the core purpose, then covers query usage and behavioral caveats. Every sentence adds value with no redundancy or filler. It is appropriately concise 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 covers return fields (name, @handle, bio), the synced nature, total_followed, and the connection-failure link. It does not explicitly describe pagination or limit behavior, but those are documented in the schema. Overall, it is sufficiently complete for an agent 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?

The input schema already describes all three parameters with 100% coverage. The description adds a clarifying example for query ('who do I follow in AI?') and reinforces the handle parameter's purpose, but does not significantly extend the schema's meaning. With high schema coverage, a 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?

The description clearly states the tool returns 'Accounts the user follows on X (Twitter)' with fields name, @handle, and bio. It distinguishes itself by mentioning 'from the synced follow graph', which separates it from siblings like get_twitter_profile, but does not explicitly name alternatives. The purpose is specific and 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 gives a concrete usage example for the query parameter and notes a key limitation (reads last sync, so a just-followed account may be missing). However, it does not mention alternatives or when not to use this tool versus related tools like get_twitter_profile or search_tweets, leaving some routing 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?

Given annotations include readOnlyHint=true, the description adds value by stating the data is 'live' and 'fresh from the X API,' and it discloses the behavior of returning a link when no account is connected. This goes beyond the annotation's read-only hint and provides useful context about data freshness and the no-account case.

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, well-structured sentence that front-loads the core functionality and includes a practical instruction. It avoids redundancy and stays concise while providing necessary context.

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 tool with one optional parameter, the description is complete. It covers what data is returned, mentions the live nature, and includes the no-account handling. Since there's no output schema, it could detail the return format, but the key information is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the single optional parameter 'handle' with full coverage (100%), so the description doesn't need to add much. It adds a small clarification that omitting returns all connected accounts, which is slightly more than the schema's 'Omit for all connected accounts,' effectively reinforcing it. 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?

The description clearly states it retrieves live profile stats (name, handle, follower/following counts, tweets) for connected X accounts. It distinguishes from siblings like get_my_tweets and get_twitter_following by focusing on profile stats, not tweets or following lists.

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 explains how to handle the case when no account is connected (give the user the link returned), which is a clear condition. It doesn't explicitly name alternatives like get_my_tweets, but the tool's specific purpose makes it obvious when to use it.

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, the description adds meaningful behavioral context: the tool reads the whole file at once and uses a column mapper that is influenced by the description parameter. It doesn't cover failure modes or return value behavior, but the essential behavioral traits for invoking it correctly are present.

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 not padded; each sentence contributes purpose, usage timing, lookup workflow, or parameter behavior. It could be tightened slightly, but it is well structured and front-loaded with the core purpose.

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 fully documented schema, no output schema, and minimal annotations, the description covers the important operational context: file types, when to use, how to identify the file, and how to supply a helpful description. A small gap is lack of guidance about duplicate handling or post-import confirmation, but it is not critical for selecting and invoking 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?

The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds value by clarifying when to pass object_id versus name and by explaining that the description parameter feeds the column mapper, which is genuinely helpful 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 opens with a specific verb and resource: 'Import every contact or company from a file the user uploaded.' It also names supported file types and explicitly distinguishes this tool from reading a contact list with read_file and creating records one at a time, making sibling differentiation clear.

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 when to use the tool ('whenever they want more than a couple of records created from a file') and when not to use an alternative approach ('never read a contact list with read_file and create the records one at a time'). It also gives a concrete workflow: find the file with search_graph_objects and pass object_id, or pass part of the filename as name.

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 well. It discloses ordering ('newest first'), the 'since we last looked' incremental semantics, the employer-only rule (title changes excluded), and the empty-result behavior on a watcher run ('on a run with nothing new it says so'). This goes well beyond the annotations and gives an agent accurate expectations.

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 adds value: purpose, use cases, watcher role, employer-only rule, and exclusions. It is front-loaded with the core definition and uses the NOT structure to efficiently prevent misrouting. No fluff 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?

There is no output schema, so the description must convey return semantics. It does: the list contains people, their old and new employers, newest first, and the empty case is explicitly described. Combined with the 100%-covered input schema and readOnlyHint annotation, an agent has everything needed to select and 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?

Input schema coverage is 100%, so the baseline is 3. The schema already documents days, limit, and refresh clearly, including defaults and a watcher-specific hint for days=1. The description adds no additional parameter-level meaning beyond what is already in the schema, so a 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 opens with a specific, concrete statement: 'People in the user's network who have moved to a different company since we last looked, newest first, with where they were and where they are now.' This clearly identifies the verb (list/report), resource (network job changes), and scope. It also distinguishes itself from siblings by explicitly ruling out related concepts: NOT a list of who to contact, NOT the history with one person, NOT news about a company.

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

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

The description provides explicit trigger phrases: 'Use when they ask who has changed jobs, who has moved recently, whether anything has changed at their contacts, or who is worth congratulating.' It also gives a special use case as a scheduled watcher and lists exclusions. However, it does not name specific alternative tools by name (e.g., company_signals for company news), so it falls short of the full 'alternatives' criterion.

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 numbers are live from LinkedIn, that 'all' requires five API calls because LinkedIn accepts one metric per call, and that daily series require one specific metric. These are meaningful behavioral details not present in 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?

The description is compact yet information-dense, with purpose, metrics, example usage, date behavior, daily-mode constraints, and sibling differentiation all included in four sentences. Every sentence earns its place and the most important distinction 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 read-only analytics tool with four optional parameters and no output schema, the description covers what data is returned, how parameter combinations change behavior, and how it differs from the closest sibling. An agent has enough context to select and 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 already 100%, so the baseline is 3, but the description adds useful interpretation: omitting dates means lifetime totals, passing start/end gives a window, and daily=true is for describing trends. It reinforces and slightly extends the schema without introducing all-new semantics.

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 tool as providing LinkedIn post analytics with an explicit metric list: impressions, unique members reached, reactions, comments, and reshares. It also names the sibling get_my_linkedin_posts as different, so an agent can distinguish this analytics tool from raw post-fetching.

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 concrete example questions that should route an agent here, and it explicitly contrasts with get_my_linkedin_posts by noting the live vs. synced data source. It also explains when to omit dates, pass a date window, or use daily=true, which is strong 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?

Beyond the readOnlyHint annotation, it discloses that data comes from readings recorded about twice a day, so the agent knows the count may not be real-time. It also reveals the return structure (latest, start, change, per-day/week series) and the 90-day aggregation threshold – useful behavioral detail not present in 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 with no redundancy: purpose, usage guidance, return structure, and sibling distinction. Each sentence earns its place, and the most identifying information is front-loaded.

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