AIdata

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

Annotations only declare readOnly=false, idempotent=false, destructive=false; the description goes further by stating the write-permission requirement and disclosing a non-obvious side effect (optional GA4 sync through the Analytics Admin API). It stops short of explaining what happens with duplicate titles or what the call returns, which matters for a non-idempotent create.

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

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

Front-loaded with the verb, resource and an example, then prerequisites and behavior. Most sentences earn their place, though the trailing GA4 Admin API documentation link is largely noise for an agent deciding whether to call the tool.

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

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

For a 10-parameter mutation tool with no output schema, the description covers permissions, the date/range rule and the GA4 side effect adequately. It is slightly thin on return value and duplicate/repeat-call behavior, but no critical gap prevents 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 already 100%, so 3 is the baseline. The description adds meaning beyond the schema by making the mutually exclusive date/range relationship explicit ("Provide either a single date, or a start and end date for a range") and by clarifying that GA4 sync is conditional on a GA4 connection,

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 (custom annotation on an AIdata property), reinforced by a concrete example ("Removed noindex from 130 posts"). It also explains what annotations are for, so an agent can tell it apart from get-custom-annotations, get-recent-annotations and update-annotation without opening a schema.

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

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

Gives clear when-to-use context (document site changes, campaigns, incidents so future analysis has context) and states the write-permission prerequisite and the date-vs-range choice. It does not, however, explicitly name the alternative update-annotation for modifying existing annotations or state any when-not-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?

readOnlyHint=true already establishes this is a safe read. The description adds non-obvious behavior beyond that: results are limited to team-shared annotations, and it discloses the content of the returned records (id, category, description, affected page URLs, source) 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?

Front-loaded with the core action, then scope, then return fields. Efficient overall, though the two parenthetical "etc." lists are slightly padded and the return-field sentence could be trimmed.

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

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

With no output schema, the description carries the return-value burden and does so adequately by listing the fields returned. The main gap is lack of differentiation from the adjacent get-recent-annotations tool, which an agent choosing between the two would need.

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

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

Schema description coverage is 100%, so date formats, the property id, categoryId, and includeGlobal defaulting are already documented in the schema. The description names category and URLs as returned content but adds no format or usage semantics for the parameters themselves, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get custom annotations") plus scope ("for a date range") and a visibility constraint ("only returns shared annotations visible to the team"). However, it never explicitly distinguishes itself from the sibling get-recent-annotations, leaving the agent to infer the difference between 'custom' and 'recent'.

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

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

Usage is only implied: date-range retrieval of shared annotations. It usefully notes that the returned annotation id can be "pass[ed] to update-annotation", which is a real cross-tool pointer, but it offers no explicit when-to-use or when-not-to-use guidance relative to get-recent-annotations.

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=true annotation already establishes the safety profile, and 'Read ... as Markdown' is fully consistent with it. The description adds useful context beyond the annotation: the output is Markdown text and should be used verbatim as the basis for an answer. No auth or rate-limit detail, but none is expected for a read-only doc fetch.

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 front-loaded sentences, each carrying a distinct load: what it does, where to get inputs, when to use `section`, and how to apply the output. No padding or repetition of schema/annotation content.

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

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

With readOnlyHint covering safety, 100% schema coverage, and no output schema, the description fills the remaining gap by disclosing the Markdown return format and answer-construction guidance. An agent has everything needed 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 100%, so both slug and section are already documented, setting a baseline of 3. The description adds genuine meaning on top by specifying when to pass `section` (long docs, one connection type) rather than merely repeating the schema's 'Optional section heading'.

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

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

States a specific verb (Read) and resource (an AIdata help doc or one section of it) plus the return format (Markdown). It is clearly separable from the sibling list-help-docs, which supplies slugs and headings rather than content.

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

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

Explicitly routes the agent to list-help-docs for slugs and section headings, and gives a concrete when-to-use rule: pass `section` when the question concerns one part of a long doc, with a worked example. It also states how to use the result (ground answers in the text, name menus/buttons verbatim, cite the source link).

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 already covering safety, the description adds genuinely new behavior: results are sorted by event date rather than creation date, only shared team-visible annotations are returned, and global SEO/industry annotations may be mixed in. It also links team annotation ids to update-annotation, which the annotations alone would not reveal.

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

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

Purpose and scope are front-loaded in the first sentence, followed by return semantics and a useful cross-tool note. It runs seven sentences and the update-annotation remark is somewhat tangential, but every sentence carries information rather than filler.

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

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

There is no output schema, so the description carries return-shape duty and does it: sort order (event date, newest first), visibility scope (shared only), content mix (team + global), and the id field's downstream use. Combined with fully documented parameters, an agent has what it needs to call and interpret 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 description coverage is 100%, so the schema already documents limit defaults/caps, property lookup, categoryId filtering, and the includeGlobal default behavior. The description reinforces the team-vs-global distinction but adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('get the most recent annotations') and scopes it with 'without specifying a date range,' which implicitly separates it from date-range based siblings like get-custom-annotations. It does not name any sibling explicitly, so it falls short of full 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?

Gives concrete trigger examples ('get the last 10 annotations', 'show recent events that might affect traffic'), which clearly signals the intended context. It never states when not to use it or names the alternative tool for filtered/historical queries, so no exclusions are provided.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that: the result is 'compiled with any arguments' and the agent must 'follow the returned instructions immediately' and pass the stated property ID onward. It doesn't discuss return shape details or failure modes, but it substantially enriches the agent's understanding of the call's downstream effect.

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

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

Four sentences, front-loaded with purpose, each carrying distinct information (definition, justification, ID source, post-call protocol). Dense but no filler; the final sentence is long but earns its place by encoding required follow-up behavior.

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, two-parameter tool with full schema coverage and no output schema, the description covers purpose, invocation source, and what to do with the result. The one mild gap is that it doesn't characterize the returned instructions' format, though the 'follow immediately' directive is sufficient for correct 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?

Schema description coverage is 100%, so both parameters (skill, arguments) are already documented, including the list-skills provenance of the ID. The description restates the skill-ID sourcing and the arguments notion but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource ('Fetch an AIdata skill's full instructions') plus a plain-language definition of what a skill is ('the team's authored report/analysis playbooks'). It is clearly distinguishable from list-skills, which only enumerates 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?

Explicitly states the selection condition ('prefer this over improvising when a request matches a skill') and routes the agent to the correct upstream sibling ('Get skill IDs from list-skills'). It also instructs on post-call behavior, so nothing about when/how to invoke is left to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful scope context with "All categories are team-created," implying a complete, small, shared set with no user-specific categories. It does not address pagination, rate limits, or auth requirements, so it adds moderate value 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?

Two short sentences plus a brief scope note; the purpose and the returned fields are front-loaded, and nothing is padded or repeated from 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?

For a simple read-only list tool with one well-documented parameter and no output schema, the description covers purpose, usage, scope, and even the shape of the returned objects. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and the lone property parameter is fully documented in the schema, including the pointer to list_properties. The description adds nothing about the parameter, so the baseline 3 for schema-does-the-work applies.

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

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

States a specific verb (List) and resource (annotation categories) and even enumerates the returned fields (IDs, names, colors, icons), which separates it from get-custom-annotations and get-recent-annotations by resource type. However, it never names or contrasts those siblings explicitly, so it falls short of full sibling 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?

"Use this to discover available categories before filtering annotations by category" gives a clear when-to-use trigger and a natural workflow position. No exclusions or alternatives are stated, but the context is unambiguous.

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

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

Annotations cover only readOnlyHint=true, so the description carries the rest: it discloses the fields returned per doc and the anti-hallucination constraint. It does not describe ordering, doc count, or whether the listing is complete vs paginated, so it falls short of fully 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?

Purpose and return shape are front-loaded in the first sentence, followed by usage conditions. The long run-on enumeration of topics (data sources, provider keys, billing, annotations...) is dense but each item maps to a real retrieval scenario, so it is useful rather than filler.

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

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

With no parameters, no output schema, and only a readOnly annotation, the description must supply both the return contract and the routing logic — and it does both, including the follow-up call. Nothing an agent needs in order to call this correctly is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter guidance is needed or missing.

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 precise verb and resource — listing every AIdata help doc — and enumerates the exact payload each entry carries (slug, title, summary, section headings). It also names the sibling get-help-doc that consumes the result, so an agent can separate listing from reading without inspecting schemas.

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

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

Gives explicit trigger conditions: user asks how to do something in AIdata, asks about a platform with no dedicated tool, or a tool fails due to missing setup. It routes the agent onward to get-help-doc and adds a clear prohibition against answering from memory.

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 description only needs added context, and it delivers: results are permission-scoped ('you can access') and span all teams, and it discloses derived fields such as overdue counts and earliest overdue item. It stops short of covering pagination or result-size behavior for an unbounded cross-team listing.

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

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

Front-loaded with the core action and effect, then the return contents, then the calling rule. Dense with useful content, though the long enumeration of returned fields plus the two behavioral directives makes it slightly heavier than necessary.

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

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

No output schema exists, and the description compensates by describing return contents and their meaning (including to-do counts and earliest overdue item) plus access scoping. An agent has everything needed to call it and interpret the result.

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

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

Zero-parameter tool, so the baseline is already high, but the description goes further by explaining that the returned property ID is required as the `property` argument on every other tool — cross-tool semantics an agent cannot infer from an empty 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?

Specific verb plus precisely scoped resource: lists every AIdata property accessible through the connector across all teams, and enumerates the returned fields (ID, name, team, connections, permission level, to-do counts). This clearly separates it from siblings like list-todos or list-skills, which list 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?

Explicitly states when to call it ('Call this first in a conversation') and why (to learn which tools will work on each property), plus an explicit hand-off rule: if a property shows an overdue to-do, call list-todos on it and inform the user. Both the usage condition and the named alternative with its trigger are present.

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

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

With only readOnlyHint declared, the description adds real value by enumerating the return shape (skill ID, target property, description, required arguments) — especially important since there is no output schema. It also explains why the data matters (team-authored methodology and output format). It does not mention pagination or scoping limits, which keeps it short of 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?

Two sentences, both front-loaded with the highest-value information: the first defines the tool and its output, the second gives the routing rule. No filler or repetition 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?

For a parameterless read tool with no output schema, the description covers purpose, domain terminology, returned fields, and downstream routing to get-skill. An agent has everything it needs to decide to call it and to use the result 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description's mention of 'accessible properties' usefully clarifies the implicit scope of the listing even though no input exists.

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

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

States a specific verb and resource ('List the AIdata skills') and immediately defines the domain term with a parenthetical gloss ('authored report/analysis playbooks'), so an agent knows exactly what a skill is. It also distinguishes itself from the sibling get-skill by framing itself as the discovery step and get-skill as the execution step.

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 usage context: when a user asks for a report or audit that matches a skill, prefer running the skill via get-skill over improvising. It names the alternative tool and the condition that selects it, but the guidance is framed around using get-skill rather than explicitly stating when to call list-skills (i.e., to discover which skills exist first).

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 already establishes that this is a safe read. The description adds useful behavioral context: these are team/AI follow-ups, open items should be surfaced proactively, completion is handled through save_todo, and IDs follow a specific format. It does not cover return structure or pagination, but with annotations present the disclosure burden is lower.

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

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

The purpose is front-loaded and every clause contributes useful routing information. The usage sentence is dense and somewhat run-on, but there is little wasted text.

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

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

For a simple read-only list tool with full schema coverage and readOnlyHint, the description supplies the purpose, usage triggers, sibling handoff for completion, and ID format. Nothing an agent needs in order to select and 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 property, search, and status parameters are already well documented. The description reinforces the open-items focus and gives an ID format example, but it does not add much parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: listing the team's to-do list for a property, including what these items are ('follow-ups the team or the AI noted down'). It clearly distinguishes this read operation from mutations handled by save_todo.

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 triggers: start of an analysis, before a first write, when context shows an overdue item, and when the user asks what to work on. It also names the relevant sibling tool, save_todo, for ticking off completed items.

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 flag the mutation/destructive profile, but the description adds context the annotations cannot: memories persist into the <team_memory> block of future conversations, are shared team-wide, and carry privacy/sensitivity constraints plus source-of-truth rules. This meaningfully exceeds the structured hints.

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

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

Purpose is front-loaded in the first sentence, followed by definition then a rules block, so nothing is buried. It is on the long side and the closing sentence partially restates the trigger already implied earlier, but nearly every line carries actionable constraint.

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

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

With no output schema, the description still tells the agent where the stored memory surfaces (<team_memory>), who sees it (whole team), and the safety boundaries around what may be written. Nothing needed to invoke a save/update/delete correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by specifying how content should be written (one short self-contained sentence, include relevant dates) and that update should be preferred over a duplicate save. It stops short of clarifying every field's edge cases, but adds real value 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 names precise operations (save, update, delete), the exact resource (a team memory for a property), and defines what a memory is with concrete examples (fiscal year, campaign naming rules, KPIs). This clearly separates it from siblings such as search_memories, list_properties, or the annotation 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 states exactly when to invoke the tool (user asks to remember, forget, or correct), what may and may not be saved, and directs the agent to check the <team_memory> block and prefer action=update over duplication. Exclusions and alternatives (search_memories, list_properties referenced in the schema) are covered.

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

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

Annotations only flag the tool as non-read-only, non-idempotent and destructive. The description adds real behavioral guardrails beyond that: a hard rule against deleting unless asked, a rule against auto-completing, and the instruction to announce each mutation in the reply. This is substantial context the annotations do not carry.

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

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

Front-loaded with purpose and scoping, and every sentence carries actionable guidance; nothing is filler. It reads as one dense block without paragraph breaks, which slightly hurts scannability for a 7-parameter tool.

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

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

With a fully documented schema, no output schema, and a destructive multi-action tool, the description supplies exactly the missing pieces: usage rules, duplicate avoidance, and mutation etiquette. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already defines every field, giving a baseline of 3. The description adds usage meaning for two of them – title style ('short imperative actions') and what belongs in notes ('context and the reason') – which nudges it above 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 first sentence names the exact resource ('to-do list for this property') and enumerates all five operations (add, update, complete, reopen, delete). An agent can distinguish it from the sibling list-todos, which only reads.

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

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

Explicit when-to-use ('add whenever the user asks, and also on your own initiative for concrete follow-ups'), when-not ('never delete one unless the user asks', complete only when the user says so), and an alternative to prefer (call list_todos first, update rather than duplicate). Nothing is left to inference.

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

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

readOnlyHint=true already establishes the safety profile, so the bar is lower. The description usefully discloses a data-overlap precondition (recent memories are already in the conversation block, so results may be redundant), but says nothing about return format, result count, or pagination for a search 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?

Two sentences, zero filler. Purpose is front-loaded, and the usage conditions follow immediately. Every clause earns its place by either defining the tool or routing the agent correctly.

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

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

For a 2-parameter read-only search tool with full schema coverage and readOnlyHint annotations, the definition covers purpose, invocation conditions, and the interaction with the ambient team_memory block. It lacks any hint about result shape or volume, but nothing critical to calling 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 both parameters are fully documented in structured form. The description adds only an implicit sense of 'query = topic' and 'property = scope' and no format or syntax detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource with clear scope: 'Search this property's saved team memories.' The resource ('team memories') implicitly distinguishes it from save-memory (write) and search-property-knowledge, but no sibling is named explicitly, so differentiation is inferential rather than stated.

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 two explicit, concrete conditions for when to invoke: when the <team_memory> block says older memories are not shown, or when the needed topic is absent from the block. An agent knows exactly when this tool is the right call versus relying on ambient 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds value by describing the kind of content returned (context, interpretation notes, insights), but discloses nothing about ranking, result limits, empty-result behavior, or whether property scoping is enforced.

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 front-loaded sentences: purpose, return content, then usage. No filler or redundancy, though the third sentence is the weakest and slightly hedged.

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 correctly carries the burden of explaining what comes back, and it does so at a useful level of abstraction. The remaining gap is operational detail (result count, ranking, pagination), which is minor for a read-only lookup 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 schema fully documents query, property, and tags itself, including the pointer to list_properties. The description adds no syntax, format, or filtering semantics beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

The description names a specific verb (Search) and resource (property knowledge base) and enumerates what it returns: business context, data interpretation notes, property-specific insights. That is concrete enough to separate it from generic retrieval tools, though it never names a sibling such as search-memories to make the boundary explicit.

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 offers a usage trigger ('when the user asks about topics that might have specific context stored in the knowledge base'), but that condition is hedging and self-referential, giving the agent little way to decide between this tool and search-memories or get-help-doc. No exclusions or prerequisites 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?

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true; the description adds real value on top by stating partial-update semantics ('Only provided fields change'), the permission model, and the external GA4 side effect with a link to the underlying Admin API resource. It does not, however, explain the destructiveHint=true flag or what data a bad edit could clobber, which is the one behavioral gap.

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

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

Front-loaded with the core action and the when-to-use condition, and each sentence carries information. It is slightly bloated: 'Optionally re-sync to Google Analytics (GA4) after editing' duplicates the sync_to_ga4 explanation already given earlier and repeated in the schema, and the raw documentation URL adds length for marginal benefit.

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

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

For a 10-parameter mutation tool with no output schema, the description covers permissions, partial-update behavior, the GA4 external dependency, and ID sourcing, which is close to sufficient. It stops short of describing what the tool returns or how a failed GA4 sync surfaces, which would matter given the external API call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the sync_to_ga4 special case ('pass sync_to_ga4 on its own to push an existing annotation to Google Analytics without editing it') and by pointing at the tools that supply annotation_id. That is genuine semantic amplification rather than restatement.

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

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

Opens with a precise verb+resource+scope: 'Update an existing custom annotation on an AIdata property.' It is immediately distinguishable from the sibling create-annotation, and the follow-on sentences make clear it is an edit-in-place operation rather than a creation.

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 ('when an annotation turned out to be inaccurate, unclear, or too vague'), an explicit restriction ('Only manually created annotations can be edited, by their creator or a property admin'), and routes the agent to the right siblings for IDs (get-custom-annotations, get-recent-annotations). It also carves out the sync-only use case, which no alternative tool covers.

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