briefpanel

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

Goes well beyond the annotations: it discloses the upsert behavior, the response discriminator (`created` true/false and `updatedSettings`), and the credit cost per check including followed item pages. An agent knows exactly what will happen and what it will cost before calling.

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 the action, then the dedupe rule, then the response shape, then cost. No sentence is redundant and each one answers a question an agent would otherwise have to guess at.

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

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

With no output schema, the description compensates by explaining the return discriminator and the `updatedSettings` field. Combined with the schema's parameter docs and the cost model, an agent has enough to invoke correctly 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?

Schema coverage is 100%, so every parameter is already documented with range, defaults, and null semantics in the schema itself. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema carries the load.

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

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

States a specific verb and resource ('Start monitoring a web page') and immediately clarifies the non-obvious semantic: one page per URL, with settings merged into an existing page. This implicitly separates it from update_source, though no sibling is named 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 critical usage condition is spelled out — calling this on an already-monitored URL does not duplicate, it updates — which is what an agent most needs to know before invoking. It stops short of naming alternatives like update_source for pure settings changes or pause/resume for lifecycle control.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuinely new context — the credit cost model — but leaves it unclear whether this tool itself spends credits, and says nothing about the shape of the returned balance.

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, front-loaded with the purpose, so it is compact. However, the second sentence refers to "a check" without defining it and sits in a tool that performs no such check, making it ambiguous padding here rather than in the descriptions of the tools that actually spend credits.

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 tool with full annotation coverage and no output schema, the description is nearly sufficient. The only meaningful omission is a note on what the returned balance looks like, which is minor for such a simple 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?

The tool takes zero parameters, so there are no semantics to explain; baseline 4 applies. The description correctly does not invent any 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?

States a specific verb and resource ("Get the user's remaining BriefPanel credits"), which is unambiguous and needs no sibling differentiation since no sibling deals with credits. The second sentence about check costs is on-topic but describes a different operation, slightly blurring the boundary of what this call itself 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?

No explicit when-to-use or when-not-to-use guidance, and no alternatives are named (none exist among the siblings). Usage is only implied by the credit-consumption sentence, which suggests calling this to gauge whether further checks are affordable.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's value is in disclosing the returned payload — `summary`, `author`, `language` — and that for non-priced kinds these fields constitute the entry's actual content. It does not mention behavior for an invalid or missing entryId, which is the one remaining 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?

Purpose is front-loaded and the contrast with the list tool follows immediately; every clause carries information. The emphasis on "these two fields ARE the entry's content" is slightly repetitive but justified given how easily an agent would otherwise skip this call.

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 does so concretely, including the semantic distinction between list and full-read results. For a one-parameter read tool, 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?

Schema coverage is 100% for the single `entryId` parameter, so the schema already documents it. The description only indirectly adds provenance (the ID comes from list_source_entries), which is marginal beyond the baseline.

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

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

States a specific verb and resource ("Read one item in full") and immediately contrasts the scope with list_source_entries, noting this returns prose the list omits. An agent can distinguish it from get_entry_changes/get_entry_updates and list_source_entries without opening any schema.

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

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

Gives an explicit triggering condition and the alternative that precedes it: "Use it after list_source_entries names an entry worth reading." That routes the agent through the correct workflow rather than guessing which entry-reading sibling to call.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful non-annotated behavior: results are grouped by fetch and pagination can return empty or short pages while more data remains. It does not cover auth, rate limits, or richer failure 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 two efficient sentences with no filler. It front-loads the tool purpose and then gives the critical pagination continuation rule.

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 read tool with no output schema, the description adequately covers the core return concept and the pagination contract. The phrase 'structured evidence availability' remains somewhat vague, and without an output schema the exact timeline card shape is not fully described, but the description is largely 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 schema documents entryId, limit, and cursor clearly. The description references pagination.nextCursor and pagination.hasMore, but adds little parameter-level meaning beyond what the schema already provides, 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 states a specific verb and resource: it gets one entry's change timeline grouped by fetch. It also mentions structured evidence availability, which clarifies the kind of result. However, it does not explicitly distinguish this from similar siblings such as get_entry_updates or get_source_changes.

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 pagination guidance: a page may be empty or shorter than the limit while more results remain, and the agent should continue until pagination.hasMore is false. It does not explain when to use this tool instead of get_entry, get_entry_updates, or get_source_changes, so alternative selection is left 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?

Annotations already declare read-only, idempotent, closed-world behavior, so the description doesn't repeat that. Instead it adds genuinely non-obvious behavior: pages may be empty or short while more results exist, and the agent must keep following pagination.nextCursor until pagination.hasMore is false. That is exactly the kind of pagination nuance an agent would otherwise get wrong.

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 short sentences, front-loaded with what the tool returns, then provenance, then the continuation rule. No filler and no restatement of the title or annotations.

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

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

With no output schema, the description compensates by naming the response fields that matter for continuation (pagination.nextCursor, pagination.hasMore) and warning about short/empty pages. The remaining gap is the unresolved overlap with get_entry_changes, which matters given the near-identical sibling names.

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 'entryId', 'field', 'limit', 'cursor', and 'importance' are already fully documented with enums and ranges. The description adds nothing parameter-specific beyond naming pagination.nextCursor as the source of the cursor, 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 one entry's typed update history') and adds an anchoring reference ('Mirrors the REST entry-updates endpoint'). However, it never distinguishes itself from the very similarly named sibling get_entry_changes, leaving the agent to guess which one returns 'updates' vs 'changes'.

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: the entryId requirement and the 'field'/'importance' filters suggest this is for inspecting a single entry's history. There is no explicit statement of when to choose this over get_entry_changes or get_entry, which is the main ambiguity an agent faces here.

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?

Despite annotations already declaring it read-only, idempotent, and non-destructive, the description adds extensive behavioral context: absent nextCheckTime conditions, stored vs effective monitoring frequency, sensitivity bands, list read coverage, dropped-item accounting, and retry semantics. There is no contradiction with the 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 purpose and usage guidance are front-loaded, but the body is a very long, dense paragraph with repeated explanations of itemsRepeated, itemsDropped, and itemsDroppedLost. The repetition and wall-of-text structure make it far less concise than it could be.

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

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

Because there is no output schema, the description carries the full burden of explaining returned fields and edge cases. It does so exhaustively, covering settings, frequency semantics, sensitivity levels, list coverage, dropped items, cut state, and retry behavior, so an agent has enough context to interpret the response.

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

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

There is only one parameter, sourceId, and the schema already covers it at 100% with 'The source ID to read.' The description does not add syntax, format, or validation meaning beyond the schema, so the high-coverage baseline 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 immediately states a specific verb and resource: 'Get one monitored page in full,' and explicitly notes that it includes settings returned by add_source/update_source but not list_sources. This distinguishes it from its siblings without ambiguity.

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 usage guidance: read a setting through this tool before changing it, and call it again to confirm the change landed. It also names list_sources as an alternative that lacks these settings, making the when-to-use and sibling routing clear.

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

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

Beyond the annotations (which already cover read-only, idempotent, non-destructive), the description discloses genuinely useful behavior: the filtered and unfiltered reads agree and neither is a partial history, and a page can be empty or short while more results remain. That empty-page caveat is exactly the trap an agent would otherwise fall into and stop paginating early.

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 scoping rule and completeness guarantee are front-loaded and the pagination warning closes it well. The middle clause ('Either way the read is complete... so the two agree and neither is a partial history') restates the same idea in two ways and could be tightened without losing meaning.

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 describing returns, and it does list the notable fields plus the pagination.nextCursor/hasMore contract, which is sufficient to drive the pagination loop. It stops short of describing the full response shape, but an agent can call it correctly without more.

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 real meaning for sourceId: narrowing returns exactly the subset the unfiltered feed would have reached for that page, which tells the agent the two calls are consistent rather than disjoint. Other parameters (limit, since, cursor, importance) are left entirely 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 ('Get item-level updates across monitored pages') and enumerates the payload (importance, field values, price deltas, entry context), so the agent knows exactly what it returns. It does not, however, name or contrast itself with the closely related siblings get_entry_changes and get_entry_updates, leaving that disambiguation to inference.

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 conditional rule: pass sourceId to read one page, omit it for the whole account. It also supplies operational guidance for advancing via pagination.nextCursor until hasMore is false. Missing is any explicit when-not or reference to the sibling change-feed tools.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: result ordering, the fact that item prose is excluded, and the non-obvious distinction that an empty first page means the page holds no items at all rather than no recent changes. It also warns that a page can be empty or shorter than limit while more results remain, which is exactly the trap an agent would fall into.

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 load (scope/fields, sibling exclusion, entryId acquisition, pagination and empty-result semantics) with the core purpose front-loaded. No filler or 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?

No output schema exists, and the description compensates by naming the returned fields and the pagination envelope members (nextCursor, hasMore). For a read-only list tool with full param coverage, nothing an agent needs in order to call it correctly or interpret results is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description goes slightly beyond by explaining how limit and cursor interact operationally — short pages are not terminal and the caller must keep following pagination.nextCursor until pagination.hasMore is false. It does not restate the limit bounds or defaults, which the schema already covers.

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

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

States a specific verb and resource ('List the items one monitored page currently holds') plus the exact fields returned (IDs, titles, URLs, prices, tracked attributes) and the sort order (most recently updated first). It also names the sibling it is not — 'read an item in full with get_entry' — so the boundary against get_entry is 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?

Explicitly says when to use get_entry instead (item prose: summary, author, quote/article/posting) and positions itself as the way to obtain an entryId for get_entry_updates and get_entry_changes, with the rationale that unchanged items appear in no change feed. Alternatives and the condition selecting them are both spelled out.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds substantial beyond-annotation context: how coverage and item counts relate, why itemsDropped can be normal, when nextCheckTime is absent, and how listReadCut differs from lastListRead.

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, but the rest is a dense, run-on block of roughly 380 words with repetitive and convoluted sentences. Much of the field-interpretation detail could be tightened or structured into clearer clauses without losing meaning.

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

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

With no output schema, the description does a thorough job explaining nuanced return fields such as lastListRead, coverage, itemsDropped, itemsDroppedLost, listReadCut, and nextCheckTime. It does not describe basic page identity fields (e.g., id, url, name) that the response likely includes, leaving a small completeness gap.

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

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

Schema coverage is 100%, so the schema already documents limit and cursor. The description adds useful usage context: a page can be empty or shorter than limit while more results remain, and the agent should continue with pagination.nextCursor until pagination.hasMore is false.

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 states a specific verb and resource: 'List the user's monitored pages with their current monitoring and fetch health.' It also distinguishes itself from siblings by noting that it does not carry monitoring instructions or sensitivity and directing the agent to get_source and list_source_entries for those.

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 alternatives and the conditions that select them: call get_source for one page's full settings, list_source_entries for the items it holds. It also gives concrete guidance on trusting lastListRead, interpreting coverage, and continuing pagination until pagination.hasMore is false.

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=false; the description adds the genuinely useful fact that the pause is reversible and points to the exact tool that undoes it. It stops short of saying whether collected history is retained or whether an in-flight fetch is aborted.

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 with no waste: the action first, then the reversal path. 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?

For a one-parameter, non-destructive, idempotent toggle with annotations covering the safety profile and no output schema, the description supplies what an agent needs to call it and undo it. The only real gap is what 'pause' does to existing data and polling 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?

Schema coverage is 100% and the single parameter is documented in the schema ('The source ID to pause.'), so baseline 3 applies. The description adds no format, source of the ID, or validity detail beyond the schema.

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

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

States a specific verb and resource ('Pause monitoring for a page') and explicitly names the inverse sibling resume_source, so an agent can distinguish it from resume_source, get_source, and update_source without opening any schema.

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

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

Names the counterpart tool and the condition that selects it ('call resume_source to start it again'), giving a clear routing pair. It does not spell out an explicit when-not scenario (e.g., prefer update_source to disable permanently), so it falls just short of full alternative coverage.

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

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

Goes well beyond the annotations: it clarifies what is affected ('changes extraction rules only and never touches items already collected'), the cost model (one credit on success, nothing on failure), and the failure mode (refused with noCredits at zero balance). These are operationally critical details annotations cannot express.

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 packed sentences, front-loaded with purpose then conditions then safety/cost. Every clause carries distinct information with no 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 one-parameter non-destructive mutation with no output schema, the description covers purpose, triggers, side effects, cost, and failure handling — everything an agent needs before invoking 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?

Schema coverage is 100% and there is a single required sourceId already documented in the schema, so the description adds nothing further about parameters. 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 ('Re-analyze how a monitored page is structured') plus the downstream effect ('later checks extract it with freshly learned rules'). This mechanism distinguishes it from the neighbouring update_source/get_source tools without needing the schema.

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

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

Explicit trigger conditions: 'Use when a page was redesigned, or when its items are being extracted wrongly.' It gives clear when-to-use context but does not name an alternative (e.g. update_source) or state 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?

Goes well beyond the annotations: discloses the billing cost ('spend credits again, one per page read'), the polling frequency, the catch-up diff behavior of the first check after a long pause, and the subtle split between the stored status field and whether checks will actually run (weekly check vs creditPaused). The no-op/'alreadyActive' claim is consistent with idempotentHint=true rather than contradicting it.

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

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

Front-loads the action and the pause_source anchor, then layers cost, idempotency, and status semantics in decreasing priority. It is dense rather than padded, though the credit-paused explanation is long-winded enough to risk burying the actionable parts.

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 itself and does so: it names the alreadyActive and creditPaused states and explains what status actually represents. Nothing an agent needs before calling or interpreting the result 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?

Only one parameter and schema description coverage is 100%, so the schema already explains sourceId fully. The description adds nothing about the ID's form or provenance, which is acceptable at this coverage level but earns only the baseline.

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

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

States a specific verb and resource ('start monitoring a paused page again') and immediately anchors it against the sibling pause_source as its counterpart. An agent can distinguish it from add_source, get_source, and pause_source without opening any schema.

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

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

Explicitly defines the trigger condition (a paused page) and the degenerate case ('already monitored is a no-op, reported as alreadyActive'), and routes to get_credit_balance as a precondition check. It does not explicitly say to use add_source when the page was never monitored, so the boundary with that sibling 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?

Annotations already declare non-destructive, idempotent mutation, and the description reinforces the scope boundary against pause_source. Beyond that it adds nothing the annotations don't: no mention of credit cost from prompt re-learn, no partial-update semantics (unspecified fields untouched), no permission prerequisites — all of which live only in the parameter 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?

Two short sentences, zero waste, with the scope statement front-loaded and the alternative routing second. Nothing to trim and nothing buried.

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 6-parameter mutation tool the description is thin: it omits that this is a partial update (only supplied fields change) and that a prompt change incurs a re-learn cost — both recoverable from the schema but not surfaced at selection time. Adequate to call correctly, not complete.

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

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

Schema description coverage is 100%, so every parameter including the credit/scheduler nuances is already documented at the field level. The description adds no parameter meaning beyond the schema, which is acceptable given the coverage but earns only the baseline.

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

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

States a specific verb and resource ("Update ... a monitored page") and uses "ordinary settings" to signal the non-lifecycle mutations, which separates it from pause_source. It never enumerates which settings count as "ordinary," so the agent must open the schema, but the intent is 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?

Explicitly routes stop-monitoring intent to pause_source, which is a genuine exclusion. However, it gives no guidance on relearn_source versus changing userPrompt here, even though the schema notes a prompt change triggers re-learning and a sibling dedicated to that exists — the one overlap most likely to cause mis-selection is unaddressed.

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 readOnly=true, idempotent=true, destructive=false and closed-world, so safety is covered. The description adds the useful detail that the response carries both the identity and the granted scopes, which the annotations do not convey — though it says nothing about failure modes for invalid or expired keys.

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?

One sentence, zero padding, and the key information (identity + scopes of the current key) 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?

With no output schema, the description must sketch the return value, and it does so at a high level (identity and scopes). For a zero-argument diagnostic tool whose annotations cover the safety profile, that is nearly sufficient — only the precise shape of the returned payload is left open.

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 no parameter semantics to explain; baseline 4 applies. The description correctly implies no inputs are 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?

Specific verb plus resource: 'Return the identity and scopes tied to the current API key.' Nothing in the sibling list does anything similar, so an agent can distinguish it immediately.

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

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

Usage is only implied — a diagnostic 'who am I' call — and no when/when-not conditions or alternatives are stated. In practice no sibling overlaps, so the risk is low, but the guidance is inferred rather than written.

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