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

Goes well past `readOnlyHint`: documents partial success semantics (`not_found` instead of an error, with the reasons ids may not resolve), warns that `data` order is not guaranteed and must be matched by `id`, and lists the error classes including the invalid-batch cases. This is the kind of non-obvious behavior an agent would otherwise discover only by failing.

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 what the tool returns and why it exists, then batching advice, then the failure modes. Short paragraphs with emphatic bolding on the one fact most likely to be missed (result ordering). No filler sentences.

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

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

Single-parameter read tool with an output schema, and the description still covers the parts the schema can't: why batching matters, how partial failures surface, and that order is unstable. Nothing an agent needs in order to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by naming the provenance of the ids (activity rows from `list_activities`), restating the 1–100 batch bound in context, and warning that digest ids silently degrade to `not_found`. It does not add format-level detail beyond the schema, which is unnecessary here.

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 plus the endpoint it wraps, and frames the tool's role as hydrating the section-specific detail that `list_activities` deliberately omits. An agent can immediately tell it apart from `list_activities` and `get_digest` without opening a schema.

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

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

Explicitly says where the ids come from (`list_activities` results), instructs batching over repeated single lookups for one rate-limit hit, and gives an exclusion rule: digest ids go to `get_digest`, not here. Use/no-use conditions and the alternative are both named.

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

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

Annotations only declare readOnlyHint, yet the description discloses non-obvious semantics: per-section item caps, that `leadership` items are change events and first-scan people carry `initial_run: true`, and that a `web-technologies` item can be an unchanged scan with empty added/updated/removed. It also enumerates concrete error codes (`not_found`, `competitor_inactive`, `forbidden_competitor`, `unauthorized`, `rate_limited`) with their meanings.

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 operation, then organized into scannable blocks (section caps, caveats, chaining, errors) that each serve a purpose. The long section/cap enumeration is the closest thing to padding, since an output schema exists and the caps could arguably live there, but it still informs interpretation of the response.

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 tool with an output schema, the description covers everything left open: response shape, per-section truncation limits, ambiguous field semantics, failure modes, and routing to siblings. Nothing an agent needs to invoke or interpret it is missing.

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

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

Schema coverage is 100% and the single `id` parameter is already documented as 'Competitor id from `list_competitors`', so the description's chaining line largely restates the schema. It adds no format, validation, or edge-case detail beyond that. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Returns a single competitor's full profile') and immediately names what the payload includes (recent items per tracked section). Sibling differentiation is explicit: list_activities is named for the full-list and timeline cases, so the agent can tell the two apart 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 the precondition ('Use after list_competitors — pass the `id` from a result row') and two explicit alternatives with the exact parameters that select them (`list_activities` with `competitor_ids=[id]` and `sections=[...]` for full lists; `list_activities` with `competitor_ids=[id]` for a timeline). When-to-use is fully resolved.

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. Description adds value by specifying returned data fields and error types (not_found, forbidden_competitor, etc.), providing behavioral context beyond 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 concise sentences: core action, chaining instruction, error list. No fluff, front-loaded with key 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 output schema exists, description covers purpose, usage, parameters, and errors sufficiently. Complete for a single-resource fetch 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% with clear description for id parameter. The description reinforces parameter usage by specifying it comes from list digests results, adding chaining context.

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 clearly states verb (returns), resource (digest), and content (executive summary, themes, update count). Distinguishes from sibling list tools by specifying single digest retrieval.

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

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

Explicitly says to use after list_digests or list_latest_digests and pass the id. Lists common errors. Does not explicitly state when not to use or mention alternatives, but chaining context is clear.

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

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

With readOnlyHint already covering safety, the description still adds substantial behavior: heavy fields are omitted from rows, default limit is 50 for tool-result size, backfilled items appear on the roster, and specific error codes are named. That is far beyond what the annotations 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?

Front-loaded with the endpoint and the two-mode split, then segmented with bullets for filters, section notes, pagination, and errors — easy to scan. It is long, and a few lines (limit default, cursor mechanics) restate the schema verbatim rather than adding 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?

Covers everything an agent needs despite seven params and a large result surface: pagination loop (`has_more` -> `next_cursor`), truncated fields and the follow-up call to hydrate them, error taxonomy, and section-specific caveats. An output schema exists, and the description correctly avoids re-explaining return shapes.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds non-obvious semantics: supplying EITHER from or to switches off roster mode, change_type collapsing rules for leadership and web-technologies, and a title/url matching tip. Some of the limit and cursor text merely repeats the schema descriptions, which keeps it from a 5.

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

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

States a specific verb and resource ('Wraps GET /activity', lists activities) and immediately decomposes it into two concrete modes, roster vs change feed, so an agent can tell exactly what it returns. It also distinguishes itself from the sibling get_activity_items by capping list rows to lean fields.

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 mode-selection rule ('no from/to = roster', 'with from/to = change feed'), a worked example request, and a named alternative for full payloads (get_activity_items). Section-specific guidance (leadership, web-technologies) further tells the agent when to include or omit change_types.

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. Description adds default expand=full behavior and error types (unauthorized, rate_limited), providing valuable context beyond 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?

Well-structured with headings and bullet points. Every sentence adds value; no fluff. Slightly longer than minimal but justified by useful detail.

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 output schema exists, description doesn't need to explain return values. Covers error types, chaining, filtering, and default behavior completely for a list 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 parameters are well-documented. Description adds meaning: defaults for expand, filtering semantics for active (tracked vs archived), and ids as comma-joined upstream. Adds value beyond schema 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?

Description clearly states it wraps GET /competitors and lists every competitor in the workspace, with scope defined. It distinguishes from siblings like get_competitor (single) and list_activities (activities).

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 when-to-use context with filtering options and chaining to other tools (get_competitor, list_activities). Could explicitly state not to use for single competitor retrieval, but sibling differentiation is implicit.

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 key behavioral traits: cursor pagination with no total (only has_more/next_cursor), and lists specific error types (invalid_parameter, invalid_cursor, unauthorized, rate_limited). 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?

The description is concise and well-structured: first sentence states core function, second paragraph lists filters, third provides chaining guidance and errors. No waste—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?

With 5 parameters, no required fields, an output schema present, and sibling tools, the description covers pagination behavior, filtering, usage advice, and errors. It is fully adequate for an agent 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?

Schema coverage is 100% so the baseline is 3. The description adds value by clarifying that from/to are inclusive bounds on period_start and reminding that cursor is opaque from previous response. This extra context justifies a 4.

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

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

The description clearly states it wraps GET /digests and returns cursor-paginated weekly digests (LLM summaries). It distinguishes itself from list_activities (no total in pagination) and list_latest_digests (one-shot), making the tool's specific verb+resource and scope very 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?

The description explicitly tells when to use this tool ('when paging backward through history, or filtering to one competitor') and when to prefer list_latest_digests ('for 'what happened last week across all competitors''). This provides clear context and 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?

Discloses that it is a read-only operation (consistent with annotation), lists possible errors (`unauthorized`, `rate_limited`), and explains the output scope without contradicting any 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 concise sentences with front-loaded information: API, no parameters, output description, chaining guidance, and errors. No wasted 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?

Given zero parameters and an output schema, the description covers purpose, usage, errors, and chaining. It is fully self-contained for an agent to invoke 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?

No parameters exist, and schema coverage is 100%. The description adds value by explaining what the tool returns (most recent digest per active competitor), exceeding the baseline of 3 for zero-param tools.

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

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

The description clearly states it returns the most recent digest per active competitor, using a specific API endpoint. It distinguishes from sibling tool `list_digests` by explaining that this is a one-shot entry point for the current batch day.

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 that no prior call is needed and advises to use `list_digests` for older weeks or specific competitor history, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true. Description adds behavioral details about auth_type behavior (api_key vs oauth), and returns subscription, budget, rate-limit. No contradictions. Goes beyond annotation by explaining when key is null.

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?

Description is concise with front-loaded main purpose, followed by useful details on auth types, chaining recommendation, and error handling. Every sentence adds value with no fluff.

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

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

Given zero parameters, readOnlyHint annotation, and available output schema, the description covers all necessary information: what it does, when to call, auth differentiation, errors. Fully complete for a simple identity 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?

No parameters, so baseline 4 applies. The schema has 0 parameters and 100% coverage, so description doesn't need to add param info. It correctly omits any parameter discussion as there are none.

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

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

The description clearly states it wraps 'GET /me' and returns workspace identity, subscription, competitor budget, and rate-limit snapshot. It distinguishes from sibling tools like list_competitors, get_competitor, etc., which have different purposes.

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 'Call first in a session to verify auth and workspace identity before any other tool,' providing clear when-to-use guidance. Also explains error handling for unauthorized and rate-limited responses.

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