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 discloses meaningful behavioral details beyond the readOnlyHint annotation: the message remains recoverable in All Mail, and current connections are generally read-only and cannot modify the mailbox. This gives the agent an accurate model of side effects and limitations without needing to test the tool.

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

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

The description is compact and every sentence adds distinct value: one explains the effect, one gives the usage rule, and one states the connectivity constraint. It is front-loaded with the most important behavioral fact and wastes no words.

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

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

For a simple two-parameter mutation with no output schema, the description covers what the tool does, its side effects, when to use it, and its permission limitations. No critical information an agent would need before calling the tool 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 documents both parameters with 100% coverage, including the option to omit 'account' to try all connected mailboxes. The description adds no new parameter-level detail, so the baseline score of 3 applies.

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

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

The description states a specific action, 'Archive one Gmail message', and clearly distinguishes the result from other operations by explaining it leaves the inbox but stays in All Mail. This makes the tool's purpose immediately distinguishable from related siblings like search_gmail_messages or 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 explicit guidance on when to use the tool: 'Use only when the user asked for the archive; confirm first if it's your own suggestion.' It also states an important constraint about legacy modify grants versus read-only connections, which helps the agent decide whether the tool is appropriate.

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 annotations only indicate readOnlyHint=false, so the description bears the burden of explaining mutation behavior. It does so well by disclosing that connecting twice with the same type is a no-op rather than an error, and by clarifying the directed nature of the edge.

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, using two dense sentences. Every clause adds information: action, examples, ID provenance, connection_type semantics, and idempotency behavior. 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?

For a three-parameter mutation tool with a full schema and no output schema, the description is nearly complete. It covers edge direction, relationship types, ID provenance, and duplicate behavior. It could be more complete by explicitly stating what response to expect or by naming when to use disconnect_graph_objects, but these are minor gaps.

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 beyond the schema by explaining that from_object_id is the edge's start, to_object_id is its endpoint, and connection_type is a relationship label with examples. It also advises using object_ids from create/search/list, which helps with parameter selection.

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 ('connect two objects with a directed edge'), identifies the resource ('the user's graph'), and provides concrete examples. It clearly distinguishes from sibling operations like disconnect_graph_objects or merge_graph_objects through the directed-edge concept.

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 the tool is for linking existing objects and tells the agent to use object_ids returned by create/search/list. However, it does not explicitly state when to prefer this over alternatives such as disconnect_graph_objects, merge_graph_objects, or create_graph_object, leaving some inference required.

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

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

Annotations only say readOnlyHint=false, so the description carries the burden. It discloses that the event lands on the real calendar immediately, that attendees are deliberately unsupported to avoid Google emailing invites, and that a reconnect result should be handled by linking to /user/integrations/gmail. This is material behavior beyond data types and 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?

Six short sentences, each carrying distinct information: purpose, usage gate, timestamp format, calendar selection, attendee limitation, and re-auth handling. There is no filler, though the required-fields reminder slightly duplicates the schema.

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

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

For a mutating tool with no output schema, it covers creation semantics, formatting, calendar routing, side-effect constraints, and failure remedy. The only notable omission is describing what a successful response contains (e.g., event id/status), but this is not critical for 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 describes all 7 parameters, so the baseline is 3. The description adds an RFC3339 example with timezone, reiterates which fields are required, and explains how to source calendar_id from list_google_calendars and what 'omit' means. This goes beyond schema but does not cover every parameter (e.g., account) in prose.

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 ('Create') and resource ('new event on the user's Google Calendar'), and clarifies scope ('one new event') so it is distinct from update_calendar_event or get_calendar_events. It also highlights required vs optional fields upfront.

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

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

Explicitly gates use on user request ('Use only when the user asked for the event'), because creation has immediate real-world effect. It also gives routing for secondary decisions (calendar_id from list_google_calendars), though it does not explicitly name update_calendar_event as the alternative for modifying an existing event.

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 the non-sending behavior, the Drafts-folder destination, the composition requirements (plain-text, no HTML/markdown, user's voice), and the legacy-grant dependency with a note that the tool reports when the grant is unavailable. This substantially exceeds what annotations 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 front-loaded with the core purpose and each subsequent sentence contributes distinct value: side effect, composition rules, sibling routing, and access restrictions. There is no filler or repetition of the title or parameter names.

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

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

For a five-parameter write operation with no output schema, the description covers purpose, side effects, when to use it, prerequisites, and even failure signaling. An agent has enough context to invoke it correctly without checking sibling tools or guessing about send behavior.

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

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

The input schema already documents all five parameters at 100% coverage, so the baseline is 3. The description adds useful semantics beyond the schema by requiring a 'specific subject', prohibiting HTML/markdown in the body, and instructing that the draft be composed in the user's voice.

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 the specific verb and resource: 'Create a DRAFT email in the user's connected Gmail mailbox, addressed to anyone.' It also distinguishes the operation from sending by stating 'Nothing is sent' and placing the result in Gmail's Drafts folder, which cleanly separates it from sibling tools like send_email.

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

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

It gives explicit routing guidance: 'Use this whenever the user wants an email written to someone else; send_email remains only for mailing the user their own address.' It also states a prerequisite and limitation: the tool only works on mailboxes connected under a legacy modify grant, and current read-only connections cannot create 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?

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?

readOnlyHint=false already signals a mutation, and the description adds meaningful side effects: linkedin_post creates a daily cloud agent that emails a digest, other types create a daily runner that emails matches filtered by the prompt, and page_url is the user's management link. It does not mention rate limits or failure behavior, but the core post-conditions are clear.

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 but dense, with examples up front and no wasted sentences. Every sentence contributes: what the tool does, how the parameters map to user intent, the behavioral difference between tracker types, and the required follow-up action with page_url.

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 importantly tells the agent to return page_url as a link and that it is the management page. It also covers the main creation flows and daily behavior. It does not address edge cases like invalid URLs or permissions, but the information an agent needs to invoke correct creation is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by mapping user phrasing to tracker_type, clarifying that a URL to watch means web_page with the URL in url and query as a short label, and reinforcing that prompt acts as a stored filter. This goes beyond the raw 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 states a specific action and resource: 'Set up a standing search the user wants watched.' It gives concrete examples, and the tracker_type variants make it clear this creates a long-running watcher rather than a one-off search. This distinguishes it from sibling search tools like search_linkedin_posts or search_slack_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?

The description clearly identifies when to use it: when the user wants a standing search or watch. It also gives explicit routing rules between tracker_type values, including the 'unless they ask for tweets/X or a specific page URL' exclusion for web_page. It does not explicitly contrast with one-off search sibling tools, but the standing-search framing is enough 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?

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?

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?

Annotations only declare readOnlyHint=true, so the description carries the burden of behavioral disclosure and does so thoroughly: events are ordered by start time, count_only sweeps up to 12,500 events and returns a per-month breakdown instead of events, and the disconnected-account error handling is specified with a user-facing action. This goes well beyond 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 dense but every sentence earns its place: it front-loads the core purpose and output, then layers defaults, time-range semantics, query behavior, count-only mode, calendar selection, and error handling in a logical order. The length is justified by seven parameters and no output schema.

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

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

With no output schema, the description fully covers return content, default behavior, count-mode output, named-calendar prerequisites, and failure handling. The schema supplies the remaining parameter details (account email, max_results), so 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?

Although schema coverage is 100%, the description adds substantial practical meaning: time_min/time_max get an RFC3339 example and a natural-language mapping ('what's on my calendar tomorrow'), query scope is expanded to titles, descriptions, and attendees, and calendar_id is explicitly tied to the output of list_google_calendars. The count_only parameter is explained with its range-sweeping behavior and ideal use cases.

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: 'List events from the user's connected Google Calendar' and enumerates the returned fields (summary, start/end, location, organizer, attendees/RSVP, meeting link). It clearly distinguishes this read/list tool from siblings like create_calendar_event and update_calendar_event without relying on the title.

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: no time range means upcoming events from now, count_only=true for 'how many meetings' questions over long ranges, and list_google_calendars is referenced as the prerequisite step for reading a named calendar. It also explains that past ranges work, so an agent knows the tool supports both backward and forward queries.

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

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?

An annotation already marks readOnlyHint, but the description adds data-source freshness (daily sync), authorization requirements, a failure signal (nothing synced), and a reconnect remedy. It also discloses newest-first ordering, going well beyond the safe-read 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, all high signal, with the core purpose and output fields front-loaded; the later sentences cover sync, filtering, and troubleshooting 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?

With no output schema, the description defines the return contents (posts with author, text, date, engagement, link plus author_counts) and ordering, and handles the empty-sync failure case. For a read-only, fully optional-parameter tool, 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 coverage is 100%, so the input schema already documents all three optional parameters. The description restates query/author behavior and adds the useful nuance that author_counts spans ALL bookmarks, but it does not materially extend the schema 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?

Description states a specific verb and resource: it returns posts the user bookmarked on X, with output fields (author, text, date, engagement, link) and a rollup. It is clearly distinguishable from siblings like get_my_tweets and get_twitter_profile by the bookmark scope.

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

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

Gives concrete context: reads the synced archive, syncs daily, requires bookmark access, and can be used directly for bookmark-frequency questions. It does not explicitly rule out alternatives or name sibling tools, but the context is sufficient.

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?

Beyond the readOnlyHint=true annotation, the description discloses the ordering guarantee, the archive-based data source with its freshness caveat for new connections, and a concrete failure mode ('reports no account connected') with the prescribed remediation. This is exactly the kind of behavioral context annotations cannot convey.

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, front-loaded with the core purpose and return fields. The sync caveat and error-recovery instruction each earn their place in a single clause; there is no filler or repetition of schema 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 read-only tool with three optional parameters and no output schema, the description covers the return fields, ordering, data freshness limitation, and the no-account failure path with the follow-up action. An agent has everything needed to select, invoke, and handle failures 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 mentions that `query` filters tweet text, but the schema already specifies a case-insensitive substring filter in equal or greater detail, and `limit` and `handle` are fully documented in the schema. The description adds no meaning beyond the structured definitions.

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 ('user's own tweets, newest first, from their connected X (Twitter) accounts') and enumerates the return fields (text, engagement metrics, date, link). It is readily distinguishable from sibling tools get_twitter_profile and get_twitter_following, which cover profile data and follow relationships rather than the user's own posts.

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 operational context: data comes from a synced archive so it is fast but may lag for brand-new connections, and it prescribes the exact recovery action if no account is connected ('tell the user to connect one at /user/integrations/twitter'). It does not explicitly name sibling alternatives or state when-not-to-use, which keeps it from 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?

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?

Beyond the readOnlyHint annotation, the description discloses ordering (oldest first), that only saved messages are returned, the channel enablement prerequisite, and the meaning of an empty result with a remediation path. This is strong behavioral context for a read-only 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?

Every sentence carries load: the first defines the result and ordering, the second defines the availability boundary and empty-result interpretation. There is no redundant 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 simple two-parameter read operation with no output schema, the description gives enough to call it correctly: data scope, order, and failure semantics. 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 describes both parameters with 100% coverage for channel_id and thread_ts. The description adds no extra parameter-level meaning beyond what the schema provides, so it meets the baseline but does not go further.

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 reading one Slack thread's saved messages, including parent and replies, oldest first. It does not explicitly name a sibling tool to distinguish it from, though the scope and storage limitation make it distinct from generic search or messaging 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 gives practical context: only threads from enabled channels are stored, and an empty result means the thread wasn't captured, with the fix being to enable that channel. It stops short of explicitly saying when to choose this over search_slack_messages or other Slack tools, so no exclusions are stated.

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 meaningfully extends the readOnlyHint annotation by disclosing that it reads the last sync (so recent follows may be missing), explaining that total_followed is the synced total, and giving explicit user-facing guidance for the disconnected-account case. This adds real behavioral context beyond 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 three dense sentences with no filler. It front-loads the core purpose, then adds the sync caveat and connection fallback, all of which are necessary for correct use.

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 no output schema, the description covers essential context: what is returned, how query filters, data freshness limitations, the meaning of total_followed, and error handling when no account is connected. The optional parameters 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 description coverage is 100%, so the baseline is 3. The description adds a concrete query example ('who do I follow in AI?') but otherwise repeats the schema's parameter semantics. It does not substantially deepen understanding of limit or handle beyond their existing 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 ('Accounts the user follows') and resource ('synced follow graph'), and enumerates returned fields (name, @handle, bio). This clearly distinguishes it from siblings like get_twitter_profile or get_my_tweets, even without naming them explicitly.

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

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

The description provides clear operational context: it reads from the last sync, explains the `query` filter usage, and instructs the agent on what to do if no account is connected. However, it does not explicitly state when not to use this tool or name alternative tools, so it falls short of a 5.

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

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

Annotations already mark this as read-only, and the description adds useful behavior beyond that: it returns live data from the X API and reports when no account is connected, including the exact user-facing connection path. This exceeds the minimal safety signal provided by readOnlyHint.

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

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

Two tightly written sentences: the first names the resource and data fields, and the second provides a practical fallback instruction for the no-account case. There is no filler or repetition of schema 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 one-optional-parameter read-only tool with no output schema, the description is complete: it enumerates all returned fields, clarifies the data source, and covers the main user-facing failure mode. Nothing essential is missing for an agent to invoke and interpret the tool.

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

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

Schema description coverage is 100%, so the handle parameter is already documented as an optional connected @handle, with omission meaning all accounts. The description adds no new parameter semantics beyond this, which matches the baseline expectation for high schema coverage.

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 job: retrieving live profile statistics (name, handle, follower/following counts, tweet totals) for the user's connected X accounts. It uses a specific verb and resource, but it does not explicitly differentiate itself from sibling tools such as get_my_tweets or get_twitter_following.

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 to use the tool: for live profile stats of connected X accounts, with guidance to have the user reconnect when no account is found. It does not explicitly mention alternatives or exclusions, but the purpose statement is specific enough to imply appropriate usage.

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?

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?

The readOnlyHint annotation already communicates safety, and the description adds valuable behavioral detail: it returns system labels as well as custom labels and includes their ids. This enriches the agent's expectation of the output beyond what the annotation alone provides.

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

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

The description is two concise sentences with no redundant wording. It front-loads the tool's core function and then immediately gives the usage 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 read-only listing tool with one optional parameter and no output schema, the description is complete enough: it states what is returned (labels with ids), the mailbox scope, and the primary user-intent trigger. The account parameter behavior is documented in the schema.

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

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

Schema description coverage is 100%, and the optional 'account' parameter is already fully documented in the schema. The tool description does not add further meaning to the parameter, so the 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 specifies a concrete verb ('List'), a precise resource ('labels in the user's connected Gmail mailboxes'), and clarifies the scope by naming system labels and user labels with ids. It is unambiguous and clearly distinct from siblings like list_google_calendars or search_gmail_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?

The description gives a clear when-to-use trigger: 'Use it when the user refers to one of their labels by name.' It does not explicitly state when not to use it or name alternative tools, 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 already declare readOnlyHint=true, and the description adds useful behavior beyond that: it lists calendars across all connected Google accounts, exposes the primary flag and access role in the response, and indicates that the tool can signal an account needing reconnection. It does not cover pagination or ordering, but for a simple list 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?

Three compact sentences with no filler: the first states action and output, the second gives the primary use case, and the third handles the error flow. Everything earns its place and the key 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 zero-required-parameter read-only list tool, the description covers the return contents, the most likely downstream call, and the reconnect handling. No output schema exists, but the description gives enough shape for an agent to know what to expect.

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 single 'account' parameter is already well documented in the input schema. The tool description adds no new parameter-level meaning, so the 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 opens with 'List the calendars in the user's connected Google account(s)' and names the returned fields: name, id, primary status, and access role. It clearly distinguishes this from get_calendar_events by framing it as the precursor step to reading events.

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 states when to use the tool: to find a named calendar before calling get_calendar_events(calendar_id=...). It also provides guidance for the reconnection case, telling the agent to link the user to /user/integrations/gmail, so the agent knows both the normal and error-path usage.

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, and the description adds meaningful behavior beyond that: newest-first ordering, counts by type, and the graph's role as a personal CRM object store. No contradiction with annotations, though it does not mention pagination or rate-limit 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?

Four sentences, all substantive, with the core behavior front-loaded before context and routing guidance. No filler or redundant restating of the schema.

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

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

For a read-only listing tool with two optional parameters and no output schema, this is nearly complete: purpose, ordering, counts, filtering behavior, allowed types, and an alternative are all covered. It could specify the exact shape of the returned counts, but nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving concrete example values ('fact', 'web_link'), explaining the effect of omitting type, and tying the type parameter to user intents like 'what files do I have?' and 'list my facts.'

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 concrete operation: list objects in the user's graph, with ordering ('newest first') and aggregate behavior ('counts by type'). Clearly distinguishes itself from sibling search_graph_objects by explicitly routing name-based lookups elsewhere, and from get_graph_object by being a list 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?

Provides direct when-to-use guidance: filter by type to browse one kind, omit type to see the whole graph. Explicitly names the preferred alternative for name-based search: 'For finding something by name, prefer search_graph_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?

Beyond the readOnlyHint annotation, the description explains the semantic meaning of results: missing integrations are not offered, `suggested` is prioritized with user-terms payoff, and connecting is always a browser grant handed to the user, never performed by the assistant. This adds valuable disclosure that annotations alone do not convey.

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 front-loaded with the core return contract, then layers usage rules, missing-integration semantics, suggested-field meaning, and connection behavior. Each sentence earns its place; no filler or repetition of the schema exists.

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 carries the burden of explaining return values, and it does: connected flags, accounts, unlocked tools, URL, and the suggested field. It also covers the critical failure mode (guessing connectivity) and the user-facing connection flow, making it complete 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 single optional `key` parameter is already documented as 'Ask about one integration only.' The description does not add new parameter-level meaning beyond confirming the default all-integrations behavior, so it stays at the schema-covered baseline.

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

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

The description names a specific verb ('Returns every integration available') and resource, and details exactly what the output contains: connected status, accounts, tools unlocked, and manage/connect URL. This clearly distinguishes it from sibling tools like get_connection_details or search_connections, which are narrower in scope.

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 call conditions: invoke before telling anyone to connect anything, and before claiming a source is unavailable. It also instructs when to use the `suggested` field and what not to do (do not suggest integrations missing from the list), providing concrete guidance an agent can act on.

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, and the description adds useful behavioral context: no search term is required, results are sorted most recently changed first, and results can be scoped by vault, folder, or tag. It stops short of describing the exact return payload, which is a minor gap given there is no output schema, so it does not earn a 5.

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

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

Three sentences with no filler. The first sentence states action, ordering, and filters; the second gives usage contexts; the third routes to the alternative tool. Every sentence earns its place and the key scoping constraint 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?

The description is complete enough for selection and invocation: it explains what is returned conceptually, how results are ordered, what filters exist, and when to use a sibling. Because no output schema exists, a slightly more explicit statement of the note fields returned would make it fully complete, but this is a moderate gap rather than a critical one.

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 parameters are already well documented. The description re-expresses vault/folder/tag options in prose but does not add meaningfully new parameter-level details beyond what the schema already states. The baseline of 3 is appropriate.

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

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

The description states a specific action ('Browse the user's synced Obsidian notes') and differentiates it from search_obsidian_notes with 'without a search term' and 'most recently changed first'. It clearly identifies the resource and scope, so an agent immediately understands what this tool does and how it differs 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?

The description gives concrete use cases: answering what a folder holds, what the user has written lately, or showing them what came across. It explicitly names search_obsidian_notes as the better tool when looking for something specific, giving an agent clear 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 already mark this as readOnlyHint=true, and the description adds meaningful behavioral detail beyond that: it discloses the empty-list response with setup instructions when no vault is synced. It also states the type of information returned, which is useful for agents anticipating the tool's output.

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 the tool returns, when it should be called, and the edge case of no synced vaults. The description is front-loaded with the core action and return value, and contains 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 parameterless read-only tool with no output schema, the description is fully sufficient: it explains the tool's scope, the returned fields, the intended invocation timing, and the behavior in the empty case. Nothing needed to call it correctly is missing.

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

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

The tool has zero parameters and schema description coverage is 100%, so the baseline is 4. There is no parameter ambiguity, and the description correctly focuses on behavior rather than inventing parameter details that do not 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 begins with a specific verb and resource: 'List the Obsidian vaults the user has synced into their Second Brain.' It also enumerates the returned data (note counts, folders, tags, last sync), which clearly distinguishes this vault-level tool from sibling tools that operate on notes or 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?

The description gives explicit guidance: 'Call this before answering anything about their Obsidian setup' and lists concrete situations such as checking whether a vault is connected or what it contains. It stops short of naming sibling alternatives like list_obsidian_notes or search_obsidian_notes, so the contrast with alternatives is implied 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 annotation, the description discloses important scope limitations: it only returns channels/DMs 'the user's brain knows about', includes per-workspace grouping, and indicates what data is returned. This helps set expectations about coverage and output content, though details like pagination or response format aren't mentioned.

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 what the tool returns and its scope, and the second sentence gives an actionable use case. Every part adds value.

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

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

For a zero-parameter listing tool with no output schema, the description is complete: it tells the agent the input (nothing), the output scope (known channels/DMs per workspace), the key fields, and the intended purpose. No essential information 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?

The tool has zero parameters, so the description doesn't need to clarify parameter behavior. The baseline for zero-parameter tools is 4, and the description does enough by explaining what the result contains.

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: lists Slack channels and DMs known to the user, per connected workspace. It also specifies the included fields (ingest status, message count) and distinguishes itself from message-search and posting tools by naming its role in resolving channel names to ids.

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 clear usage context: use it to resolve a channel name to its id before searching or posting. It doesn't explicitly name sibling alternatives or state when not to use it, but the instruction is concrete enough for an agent to know when to invoke 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?

The description goes far beyond the annotations by fully disclosing side effects: connections are moved, missing fields are copied without overwriting, an audit marker is appended, and the duplicate is deleted. It explicitly warns that the operation is destructive, irreversible, and requires explicit consent. This is exactly the behavioral context an agent needs.

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

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

The description is compact, front-loaded with the core action, then efficiently details side effects and the mandatory safety procedure. Every sentence contributes necessary information, and there is no redundant or filler 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 destructive merge tool with no output schema, the description covers all essential behavioral aspects: scope restrictions, field handling, connection migration, audit marking, deletion, irreversibility, and user consent. An agent has enough information to invoke the tool safely and correctly.

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

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

Schema coverage is 100%, and the description adds meaning by explicitly distinguishing keep_id as the survivor and merge_id as the deleted duplicate. This clarifies the parameter roles 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 identifies a specific verb and resource: merging two duplicate records in the user's graph into one, and further narrows scope to person or company records. This clearly distinguishes it from sibling tools like delete_graph_object, connect_graph_objects, and purge_graph_object.

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

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

The description clearly communicates when this tool is appropriate: for duplicate person or company records in the graph. It also provides a crucial precondition: ALWAYS show both records and get explicit user confirmation before calling. It does not name specific alternative tools, but the context is clear enough for an agent to select it appropriately.

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 behavioral traits: only deliberate relationships count, bulk-imported and system-inferred edges are excluded, and an empty list is returned when no mutual connections exist. It also instructs the agent to report that absence honestly, which is valuable runtime guidance.

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

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

The description is compact and well-structured: definition first, then examples, then two key caveats. Every sentence carries useful information, and there is no redundant repetition of the title or schema.

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

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

Given the low complexity, two well-documented parameters, and readOnlyHint annotation, the description is nearly complete. It clarifies the return behavior (empty list) and the relationship filter. It does not describe the exact output structure for non-empty results, but the absence of an output schema is partially mitigated by the clear statement that graph objects are returned.

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 with 100% description coverage ('exact object_id'). The tool description adds context that these are 'two given objects' and gives examples of people/companies, but it does not need to add more since the schema is already explicit. 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 states a specific verb and resource: finding objects in the user's graph directly connected to BOTH of two given objects. It gives concrete examples (mutual contacts between people, shared people between companies), which clearly distinguishes this from generic connection or search tools like search_connections or find_paths.

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 implies when to use this tool: when you need mutual or shared connections between two entities. It does not explicitly name alternatives or exclusions, but the BOTH condition and examples provide enough contextual guidance for an agent to select it appropriately.

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 critical behaviors: unreadable fields are null and must not be guessed, and checks surfaces internal inconsistencies that must be reported to the user. This gives the agent a clear model of the tool's output semantics and obligations.

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 earns its length by covering purpose, special output fields, user obligations, and parameter usage. The structure front-loads the main purpose and then explains the non-obvious parts. Only the final rhetorical sentence could be trimmed without losing essential 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 tool with no output schema, the description thoroughly explains what fields are returned and what the special unreadable and checks fields mean. It also covers how to identify the target file, making it nearly self-sufficient for correct invocation.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds value by explaining how to populate them: find the file with search_graph_objects and pass object_id, or pass part of the filename as name. This is a meaningful supplement to 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: 'Read an invoice PDF... and return its fields', then enumerates the exact fields returned. This clearly distinguishes the tool from generic file-reading siblings like read_file by focusing on invoice-specific structured extraction.

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 it whenever someone asks what an invoice says, what they are being charged for, whether a bill adds up, or wants an invoice turned into data.' It also gives practical guidance for finding the file via search_graph_objects, though it does not explicitly mention when not to use it or compare it to read_file.

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 only indicate readOnlyHint=false, which is minimal. The description carries the behavioral burden and does so thoroughly: it discloses permanent deletion, no undo, cascade deletion of all touching connections, and the need for explicit user confirmation. This goes well beyond 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 concise yet information-dense, with the most critical facts front-loaded: permanent deletion, no undo, user confirmation requirement, then alternatives. Every sentence contributes either a safety constraint, a usage condition, or a sibling differentiation.

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

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

For a destructive one-parameter tool, the description fully covers what the tool does, why it is dangerous, when to use it instead of alternatives, and what the parameter represents. No output schema is present, but 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 schema already fully documents the single parameter object_id as 'The object to destroy (exact object_id).' The description does not add new parameter-level detail, but with 100% schema description coverage and one required 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 states a specific verb ('Permanently delete one object'), a clear resource ('from the user's graph'), and the cascading scope ('along with every connection touching it'). It clearly distinguishes itself from delete_graph_object and disconnect_graph_objects by naming these siblings directly.

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 prefer delete_graph_object when reversibility matters, to use purge_graph_object only when the user has explicitly asked for data to be gone, and to use disconnect_graph_objects when removing only a single connection. It also instructs the agent to confirm with the user before calling, which is direct 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 annotations only declare readOnlyHint=true, so the description's note that PDFs and images are returned as the actual document with correct table and scan rendering adds meaningful behavioral context. There is no contradiction between the read-only annotation and the described 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?

Three focused sentences front-load the purpose, then add the use case, special rendering behavior, and lookup guidance. No sentence is redundant or wasted.

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

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

For a read-only file-reading tool, the description covers when to use it, how to resolve the file, which parameter to pass, and how PDFs/images behave. It is complete enough to guide correct invocation even without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the object_id-vs-name choice and the search_graph_objects workflow, but it does not materially add parameter semantics beyond what the schema already documents.

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 reads the content of a user-uploaded file in the Second Brain, with the verb and resource both specific. It distinguishes this from web-page or Obsidian-note readers by narrowing scope to uploaded documents and by naming search_graph_objects as the way to locate 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?

It explicitly says to use this when the answer may live in an uploaded document, which gives a clear triggering context. It also provides the lookup workflow with search_graph_objects, but it does not explicitly state when not to use it or name alternative reading tools such as read_web_page.

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

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

Beyond the readOnlyHint annotation, the description discloses important behavior: it renders in a real browser for JavaScript sites, returns readable text, optionally saves the page as a web_link, defaults to a non-stored one-off read, and explicitly declines to attempt unreadable pages. This is substantial transparency that meaningfully exceeds annotation information.

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?

While longer than a simple one-liner, every sentence contributes: purpose, when to use, rendering behavior, return type, persistence option, limitations, and sibling differentiation. 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?

For a simple two-parameter tool with no output schema, the description fully equips an agent: it explains what is returned (readable text), the persistence default, exclusions, and fallback alternatives. 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 the schema already documents both parameters thoroughly. The description reinforces the save behavior with the graph/search context, but largely mirrors the schema descriptions rather than adding new parameter-level insight.

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: 'Fetch and read the content of one public web page by URL.' It clearly distinguishes itself from sibling tools by explicitly naming research_company and read_file as alternatives for different use cases.

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

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

It gives explicit when-to-use guidance: 'use when the user asks what a page or article says, or you need to read a prospect's or company's own site before a conversation.' It also states exclusions (LinkedIn, social, sign-in-gated pages) and directs those cases to the browser extension, plus names non-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 mark readOnlyHint=false, so the description adds value by stating that a new interaction object is created and connected to the person. It also discloses that future timestamps are acceptable and that the person must already be a graph object. It does not cover failure modes or duplicate interactions, but this is adequate for a simple create action.

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 with a distinct job: scope and purpose, object creation and prerequisite, parameter semantics. There is no filler and no mere repetition of schema text.

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

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

For a mutation tool with five required parameters and no output schema, the description covers all the non-obvious information an agent needs: input types, date syntax, direction interpretation, and where to obtain the person's ID. No critical usage gap remains.

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 all five parameters, so the baseline is 3. The description adds real meaning for three of them: occurred_at format and future dates, direction from the user's point of view, and the source of with_object_id. Channel and summary are self-explanatory and need no extra 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?

The description opens with a specific verb ('record'), defines the resource ('one dated touchpoint' / 'interaction object'), and enumerates accepted interaction types. It makes clear that the tool creates an interaction object connected to an existing person, which distinguishes it from generic graph creation 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 gives a clear purpose — answering 'when did I last talk to them?' — and a concrete prerequisite: get with_object_id from search_graph_objects. It does not explicitly name alternatives or state when not to use the tool, so it stops just short of full guidance.

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

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

The annotations already declare readOnlyHint=true, and the description adds valuable behavioral context by warning that an uncached company can make the first run slow. It does not discuss errors or auth, but for a read-only research 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?

The description is organized with purpose first, then input/output details, then alternatives, then the latency caveat. The 'same engine behind the CompanyResearch.ai app' clause adds only marginal value and could be trimmed, but the rest 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 one-parameter read-only tool with no output schema, the description is complete: it explains input format, return profile contents, usage context, alternatives, and the important latency behavior. 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 provides 100% coverage for the single `company` parameter, including the domain-vs-name guidance and examples. The description largely restates this rather than adding meaning beyond the schema, so the 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 opens with a specific verb and resource: 'Research one specific company in depth,' and enumerates the output profile fields. It also distinguishes itself from find_companies and company_card, making its 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?

It explicitly states when to use the tool ('when the user asks to research, analyze, or get a briefing on a specific company') and names alternatives for related but different requests: find_companies for discovery and company_card for quick identity cards.

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 the description matches (saving is a mutation). The description adds valuable behavior beyond the annotation: the file appears with uploads, can be read back via read_file, refuses files over 50MB, and fails on sign-in-protected URLs. Rich behavioral disclosure with 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?

Three sentences, each carrying distinct information: core action + trigger, post-condition + read-back path, and exclusions + size limit. Front-loaded with the verb and resource. Zero 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?

For a 2-param tool with no output schema and minimal annotations, the description covers action, trigger, exclusions, size limit, storage location, and lifecycle. The only gap is the return value/confirmation shape, which would matter more since no output schema exists to document it. Otherwise complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine semantic value beyond the schema by qualifying the URL as 'public' and requiring a 'direct link', which is a real constraint not stated in the url parameter description. The filename default is already in the schema, so no duplication credit there.

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 (download from URL, store as file object in Second Brain) with concrete file-type examples (PDF, image, spreadsheet). Explicitly differentiates from siblings: read_web_page for web pages and read_file for reading saved files afterwards. An agent can tell exactly what this tool does and what it is not 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?

Gives an explicit trigger condition ('shares a direct link... and asks to save, download, or keep it') and names the alternative with its exact parameter ('read_web_page with save=true'). Also excludes sign-in-protected files. This is textbook when-to-use-vs-alternatives 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 significant behavioral detail beyond the readOnlyHint annotation: return fields, the effect of omitting filters, and the critical no_imported_data semantics that prevent the agent from making a false negative conclusion. This is exactly the kind of behavioral disclosure agents need.

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 efficient and front-loaded: the core purpose appears first, followed by concrete use cases and a brief return/behavior summary. The no_imported_data warning earns its place because it prevents a serious inference error.

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 search tool with no output schema, the description covers return contents, parameter behavior, edge-case response semantics, and the meaning of empty results. Nothing essential is missing for an agent to call and interpret 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 schema already documents each parameter well. The description adds value by providing usage examples and clarifying that omitting all filters lists recent connections, which supplements the schema without duplication.

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 and resource: 'Search the user's own LinkedIn connections by name, company, or job title.' It includes concrete example questions that distinguish this tool from broader connection-related siblings like get_connections_summary or ask_about_connections, so the agent can identify when this direct search is appropriate.

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 usage context with example queries and explicitly says to omit filters to list recent connections. It does not explicitly name alternatives or state when not to use this tool, but the context is strong enough for an agent to recognize the intended use.

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, which the description supports without contradiction. The description adds substantial behavioral disclosure: newest-first ordering, the exact fields returned, the meaning of the starred flag, the fact that total_matches_estimate is Gmail's broader estimate, the no-account error condition, and the rare header-only limitation. This far exceeds what annotations alone 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 longer than average, but each sentence carries distinct operational value: return format, sorting, query syntax, starred-flag semantics, count estimation, and error handling. The most critical routing information (what it returns and how to query) is front-loaded, followed by edge cases. No filler or tautology is present.

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 present, the description carries the full burden of explaining the return shape and behavior, and it does so thoroughly. It covers result fields, ordering, search syntax, the count estimate, connection-failure handling, and the header-only limitation. For a search tool with Gmail's complex query language, this is complete enough for an agent 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?

Although schema coverage is 100%, the description meaningfully enriches all three parameters: it explains Gmail search syntax for query with multiple examples, clarifies that omitting account searches all connected mailboxes, and ties max_results to a real example ('last 5 messages ... max_results 5'). It also adds the default/max behavior context in the schema and practical usage scenarios.

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 precise verb and resource: 'Search the user's connected Gmail mailboxes and return matching messages, newest first.' It enumerates the exact return fields (from, to, subject, date, snippet) and clearly distinguishes itself from sibling write tools like archive_gmail_message and create_gmail_draft by focusing on read-only search. It also differentiates from get_gmail_message by indicating this returns a list of messages with snippets rather than a single full message.

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 when-to-use guidance with examples: query syntax for sent/received mail, operators like newer_than and has:attachment, and how to phrase natural-language requests. It explicitly explains when to use total_matches_estimate for count questions and gives handling instructions for no-connected-account and header-only-connection cases, including the alternative of answering from the brain. This is rich routing 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 provide readOnlyHint=true, and the description does not contradict that. It adds valuable behavioral context beyond the annotation: semantic matching over text-bearing objects, matching against names and descriptions, and returning object_id values for follow-up. It does not detail ranking or match ordering, but that is not critical for a search 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?

Two information-dense sentences with no filler. The core behavior is front-loaded, the use case is stated clearly, and the return value with next-step tool is included. 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?

The description covers purpose, usage trigger, optional type restriction, and return value with object_id for follow-up. With no output schema, it appropriately summarizes what the agent can expect. It could mention result-order or empty-result behavior, but the description is sufficient for safe 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 the baseline is 3, but the description adds real meaning beyond the schema: it clarifies that query is not just exact-match but semantic, and that type is an optional restriction. This helps the agent understand how query behaves in practice.

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 ('Search the user's graph by matching a term against object names and descriptions') and adds the distinguishing semantic-matching behavior. This clearly separates it from sibling search tools like search_connections or search_gmail_messages by scope and mechanism.

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

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

Explicitly says when to use the tool: to find a specific thing the user mentioned when you don't have its object_id, and even names get_graph_object as the follow-up. It does not explicitly state exclusions such as 'for browsing all objects use list_graph_objects,' but the use case 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?

Annotation Contradiction: readOnlyHint is true, but the description explicitly says the tool 'store[s] the results in the user's brain automatically' and tells agents not to re-save them with graph tools. That describes a persistent write side effect, which contradicts the read-only annotation. The rich operational detail is therefore undermined by this inconsistency.

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

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

The description is front-loaded with the main action, followed by compact, non-redundant sentences about output split, watcher behavior, linking syntax, and the found_by_object_id parameter. Every sentence earns its place despite the paragraph being longer than average.

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?

Without an output schema, the description compensates by explaining the new/seen response split, how to link posts using returned object ids, and the scheduled-watcher reporting rule. That gives an agent everything needed to invoke the tool and handle its return 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 real value for found_by_object_id by explaining that it is the agent's own node id from the [object:...] marker and should be omitted in normal chat; this goes beyond the schema's field description.

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

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

The opening sentence names a specific verb+resource ('Search public LinkedIn posts by keywords') and adds the distinctive side effect (auto-store results), which separates it from sibling read tools like get_my_linkedin_posts 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?

The description gives clear context: scheduled watcher runs should report only new posts, found_by_object_id should be omitted in normal chat, and results should not be re-saved with graph tools. It does not name an alternative tool to use instead, so it stops short of a full when-to-use-vs-alternative statement.

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

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

With readOnlyHint=true, the safety profile is already covered. The description adds real behavioral value: it discloses the return shape (excerpt, location, object_id, path) and explains that search works by keyword and meaning. It also positions the tool as a gateway to get_obsidian_note.

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, no filler. The main action and return value lead, usage guidance follows, and parameter/follow-up guidance is compactly appended. 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?

The description covers what the tool does, when to use it, how to narrow results, what it returns, and how to continue the workflow. With full schema coverage and no output schema required, nothing necessary for correct selection and invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by clarifying that folder is a vault path prefix (with a concrete example), grouping vault_id/folder/tag as narrowing options, and explaining that object_id and path support follow-up with get_obsidian_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?

The description names a specific verb ('Search'), a specific resource ('notes synced from the user's Obsidian vault'), and the two search modes ('by keyword and by meaning'). It also distinguishes itself from the sibling get_obsidian_note by clearly stating it returns excerpts and locations, not full notes.

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 use-case triggers: 'when they ask what their notes say about something, or point at their vault.' It also implies when not to use it (when you need the full note, use get_obsidian_note) via the follow-up mention, though it does not explicitly list 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?

Annotations only provide readOnlyHint=true, so the description carries most of the behavioral burden. It adds meaningful context: the coverage limits, newest-first ordering, and what to do when no Slack workspace is connected. It doesn't fully explain the 'by meaning' mechanism or return shape, but it goes well beyond 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 and efficiently structured: action with scope, optional filters, and error handling each get one clear sentence. Every sentence earns its place, and the most important capability 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 search tool with fully documented parameters, the description covers the search scope, ordering, optional filtering, and the no-workspace edge case. The lack of an output schema is acceptable here because the tool's purpose and result ordering are clearly stated, making an agent's invocation safe and well-directed.

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 each parameter is already well described in the input schema. The description reinforces channel id/#name and ISO date formats, but it does not add significant semantic 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 opens with a specific verb and resource: 'Search the Slack messages saved to the user's brain,' and adds clear ordering behavior ('newest first'). It also defines scope precisely ('channels the user switched on and their DMs with YouSpot; nothing outside those'), which distinguishes it well from sibling search 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 scope statement clearly tells the agent what is and is not covered, and the failure-handling instruction ('If it reports no Slack workspace connected...') gives concrete next-step guidance. It does not explicitly name sibling alternatives, but the boundaries are clear enough for an agent to decide when 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?

Beyond the readOnlyHint=false annotation, the description discloses critical behaviors: recipient is fixed and cannot be changed, Markdown is rendered through a template, HTML is rejected, no sign-off is added, object links must originate from actual graph tool results, and chat links are resolved to pre-filled prompts. This is rich, actionable behavioral 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 longer than average but well-structured with sections and examples. Every major behavioral rule earns its place, though there is minor redundancy with the schema's parameter descriptions for body and links.

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 all essential invocation aspects: recipient, use cases, subject fallback behavior, body format, link constraints, required closing link, and prohibitions. An agent has enough to call the tool correctly without additional 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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining subject line composition expectations, Markdown rendering rules, and the exact semantics of object vs. chat links, including the silent-failure risk for invalid object ids.

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: sending an email to the signed-in user's own address. It explicitly distinguishes itself from the sibling create_gmail_draft, making the tool's unique scope immediately 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?

Gives explicit when-to-use triggers with quoted user phrases like 'email me this' and 'send myself a reminder'. It also names the alternative tool for emailing others and explains why create_gmail_draft is preferred in that case, providing clear exclusion 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=false annotation, the description discloses the sending identity (YouSpot), Slack markdown expectations, the invitation restriction, and the requirement to get user confirmation before visible posting. This is meaningful behavioral context for a mutating, externally visible action.

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 adds constraints in a logical order: channel eligibility, ID discovery, formatting, and user confirmation. Every sentence contributes practical information with no redundancy.

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

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

For a simple send operation, it covers the target, identity, allowed channels, message formatting, and confirmation requirement. It does not describe return values or error behavior, but these are not essential for correct invocation, and the missing details are minor for 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that text should use Slack markdown and that channel_id can be discovered via list_slack_channels. thread_ts and team_id remain adequately covered by the schema itself.

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: 'Post a message to a Slack channel or DM as YouSpot, optionally as a reply in a thread.' This clearly separates it from siblings like add_slack_reaction, get_slack_thread, and search_slack_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 gives actionable guidance: only channels the bot has been invited to work, use list_slack_channels to find ids, and confirm with the user before posting somewhere others can see it. It doesn't explicitly name alternatives, but no sibling tool duplicates this posting action, and the constraints make usage 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?

Annotations only indicate readOnlyHint=false, so the description carries the burden of behavioral detail. It transparently discloses that the tool creates a follow-up fact with follow_up_at and an optional note, connects it to the target object, and warns about the interim lack of a dated query tool. This is honest and useful, though it does not describe the exact return value or error behavior.

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

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

The description is compact and front-loaded: first sentence states purpose with an example, second defines the data created, third gives an important limitation. Every sentence contributes necessary information, with no filler or repetition of the schema.

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

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

For a simple three-parameter mutation tool with no output schema, the description is largely complete: it covers what is created, how the object is linked, and how to retrieve follow-ups under the current limitation. The main omission is the response format, but that is minor for a create-style tool and does not block correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3 even with minimal description-level parameter detail. The description adds some meaning by naming the stored field follow_up_at and noting the optional note and object connection, but it largely restates what the schema already provides for the three 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 states a specific action and resource: 'Set a dated follow-up about an object in the user's graph' and gives a concrete example. It clearly indicates this creates a follow-up fact rather than a calendar event or generic graph object, though it does not explicitly name sibling tools for differentiation.

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 makes the tool's usage context clear: use it to attach a dated follow-up to a graph object. It also provides practical guidance for reading follow-ups back by listing fact objects and filtering on json_data.follow_up_at, effectively telling the agent what to do when a query tool is missing. It does not mention alternatives or exclusions explicitly.

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