Contrie

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

Annotations only provide readOnlyHint and openWorldHint. The description adds valuable behavioral context: zero extraction credit cost, no capacity reservation, advisory eligibility with source/service/request-specific checks still applying, and an account authorization requirement. This goes well beyond the structured 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?

Two sentences with no filler. The first sentence front-loads the purpose, and the second adds cost, capacity, eligibility caveats, and authorization requirements. Every clause earns its place.

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

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

For a zero-parameter, read-only account status tool, the description is complete: it states what is read, that it is free and non-reserving, that eligibility is advisory, and that authorization is required. No output schema exists, but the description sufficiently indicates the kind of information returned.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameter semantics. The zero-parameter baseline of 4 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 names a specific verb ('Read') and a precise resource: the user's own account credits, allowance reset, and restrictions. This clearly distinguishes it from siblings like contrie_extract or contrie_read, which focus on other operations.

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

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

The description implies usage context by noting it costs zero extraction credits, reserves no capacity, and gives advisory eligibility. However, it does not explicitly name alternatives or state when not to use this tool, so the guidance is implied rather than explicit.

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

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

Well beyond the readOnly/openWorld annotations, it discloses auth requirements (OAuth or API key in Authorization), rate-limit effects, that reading does not mutate monitoring or accounting state, that it charges no credits, and that snapshot failure surfaces as SERVICE_UNAVAILABLE. It also carefully scopes the statusRead coverage claim to the monitor/status statement only, which prevents over-reading the evidence.

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 core purpose is front-loaded and most sentences carry distinct semantics (runStatus states, statusRead scope, event diff contents). It is dense and includes some defensive hedging ('Pending promises no running process, charge...') that borders on legal boilerplate, keeping it just short of a 5.

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 full burden of explaining the return shape — runStatus values and their meanings, statusRead coverage, and the before/after evidence diff on every change — and it does so thoroughly. 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?

Schema coverage is already 100%, so the schema documents all three params; the description adds real value on top by clarifying the mutual exclusion of before/eventId and the recovery semantics of each. It stops short of name-level detail but meaningfully augments 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+resource ('Read a monitor's history') and enumerates what comes back (latest answer with evidence status, last 20 events of baseline/change/error). This is far more concrete than its generic-name siblings, but it never names or contrasts with contrie_read, contrie_search, or contrie_verify, so an agent must infer which read tool fits.

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 clear when-to-use guidance for its own parameters — pass nextCursor as before for older events, or eventId to recover one exact event, and do not combine them. However, it offers no routing advice against the overlapping sibling read tools (contrie_read, contrie_search), so tool-selection guidance is only implied.

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 readOnlyHint/openWorldHint: discloses credit costs (1/3/8/15), zero cost on refusal, per-plan caps (Free 3, Builder 5, Pro 17), the 2-credit rendering surcharge, auth requirements, sample-request exception, and exactly what the returned grounding verdicts do and do not prove. This is unusually rich behavioral context.

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

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

Purpose is front-loaded and each clause carries information, but the description is dense and long – the credits/caps/pricing detail is thorough perhaps beyond what is needed to select and call the tool. Still, little is wasted for a tool with this much behavioral surface.

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 the return-shape burden and does so thoroughly (qualityScore semantics, grounding meaning and its limits, groundingFields, metadata.binding, progress, credits). Auth, cost, and scope prerequisites are all covered, leaving no gap that would block correct invocation.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds real meaning: it clarifies the interplay of NL fields vs Schema and ties rendering/cost behavior to the render parameter and cache behavior to maxAge. Guidance is useful though not exhaustive on enum edge cases.

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

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

States a specific verb and resource ('Extract structured data from one public web page') and immediately bounds scope with 'Not a crawler or a search engine: one page per call', which cleanly separates it from batch/read/verify siblings. An agent can tell what it does without opening 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?

Explains how to drive it (describe fields in natural language and/or pass a JSON Schema) and gives an explicit when-not ('not a crawler or search engine'), plus auth and cache conditions. It stops short of naming which sibling to use for multi-page or monitoring work, so routing 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?

Despite existing readOnlyHint and openWorldHint annotations, the description adds substantial behavioral detail: it performs one statusRead for a complete account snapshot even when empty, unavailable snapshots fail, stopped monitors are not listed but their history remains readable, no credits are charged, and the status output is not a recovery or financial conclusion. It also documents authentication via OAuth or API key. This goes well beyond 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 description is front-loaded with the core purpose and return fields, followed by concise behavioral notes. It is one dense paragraph rather than a list, but nearly every clause adds useful information and nothing is obviously redundant.

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

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

Given no output schema, the description enumerates the returned fields and explains account snapshot behavior, failure conditions, listing scope, cost, authentication, and status limitations. An agent has enough context to call and interpret the tool correctly.

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

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

There are zero input parameters, so the schema has nothing to document and the description appropriately focuses on output fields rather than input semantics. The baseline for a zero-parameter tool is 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 opens with a specific verb and resource: 'List your active monitors', then enumerates the exact fields returned (id, url, question, cadence, next scheduled run, latest answer, runStatus). It also scopes the result to active monitors and explicitly excludes stopped monitors, which distinguishes it from sibling tools like contrie_unwatch and contrie_watch.

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 supplies context (active-only scope, authentication requirements, no credit charge) but never names alternative tools or states when to use this tool versus siblings like contrie_account, contrie_read, or contrie_search. Usage is implied rather than explicitly guided.

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 readOnlyHint/openWorldHint annotations: it discloses the credit model (1 credit success, 0 failure), the +2 credit rendered-read surcharge, the 100,000-character cap with the sourceTruncated flag, and the authentication options (OAuth sign-in or API key header). This is exactly the behavioral context an agent needs before invoking.

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 purpose in the first clause, and nearly every sentence earns its place (cost, return shape, truncation, auth, rendering). Minor redundancy between 'Returns the full REST-shaped JSON response...' and 'Returns the page as markdown, not typed fields' costs it the top score.

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 response envelope (data null, markdown field, metadata with credits and evidence status), so an agent knows what a call returns. Combined with the auth, cost, and truncation notes, nothing needed to invoke correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already carries per-parameter detail. The description adds real connective meaning by tying the render pathway to additional credit cost and the truncation flag to evidenceCoverage, going slightly beyond the raw schema text.

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), resource (one public web page), and output format (structure-preserving markdown with boilerplate removed). The clause 'Returns the page as markdown, not typed fields' implicitly distinguishes it from a typed-extraction sibling, so an agent can route on the format alone.

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?

Some selection signals are present: 'public web page', 'not typed fields', and the render pathway for JavaScript shells. However, it never names a sibling or states when to prefer contrie_extract over contrie_read, leaving the main routing decision 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?

Adds substantial context beyond the annotations: credit cost rules (1 credit on results, 0 on empty or refused searches), authentication methods (OAuth or Authorization header API key), result cap of 10 snippets, per-snippet return fields, and an explicit prompt-injection warning to treat snippets as data, never instructions. This is exactly the kind of behavioral detail annotations cannot 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 the core purpose, then layers scope, return shape, safety warning, cost, and auth in short declarative sentences. Information density is high and nothing reads as filler, though the block is longer than strictly needed for a two-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?

No output schema exists, and the description compensates by specifying the exact return shape (title, URL, fetchedAt, contentHash, up to 10 snippets). Cost, auth, and safety caveats are all covered, leaving no material gap 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%, so both query and limit are already documented with syntax (quoted phrases, or, and -term) and bounds. The description only echoes the 10-snippet cap already present in the schema, adding no new parameter semantics. 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 — searching Contrie's curated index of public technical reference pages — and immediately scopes it by contrasting with what it is not (not the open web, no new fetches, no full text). An agent can distinguish this from generic web search without opening 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?

Clearly frames the usage context ('To read a result in full, request its URL') and enumerates exclusions (does not search the open web, fetch new pages, or return full page text). It stops short of naming a specific sibling tool for the full read, but the routing intent is unmistakable.

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

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

The description goes well beyond the annotations by disclosing that an in-progress run can still finish and be charged, that history remains readable, that the return value is a monitor with active: false, that stopping an already stopped monitor is idempotent, and that the operation is irreversible. It also covers authentication requirements and that no credits are charged.

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

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

Every sentence adds a distinct operational fact: stopping behavior, in-flight run behavior, history retention, return shape, idempotency, irreversibility, and authentication. The main action and immediate consequences are front-loaded, and there is no filler.

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

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

For a tool with one required param, no output schema, and meaningful side effects, the description is complete. It explains what happens to scheduled runs, charges, history, and the returned object, and it supplies authentication guidance, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, and the sole parameter id is already described as 'The monitor id' in the schema. The description adds only the context that it is one of the user's monitors, which is not enough to raise the score above 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?

The description states a specific verb and resource: 'Stop one of your monitors', and clarifies the consequence of no further scheduled runs or charges. It clearly distinguishes this from sibling tools like contrie_monitors or contrie_watch by describing the precise stop behavior and irreversibility.

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

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

The description gives clear context for when to use the tool: when the user wants to stop a monitor and avoid future runs and charges. It also warns that a stopped monitor cannot be restarted, which implicitly tells the agent not to use it for temporary pauses, though it does not explicitly name alternative sibling 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 only provide readOnlyHint and openWorldHint, so the description carries the burden of behavioral context. It adds substantial detail: the check charges no credits, requires OAuth or an API key, accepts URL/HTML/text, reports per-field results with excerpts, and applies literal-match semantics. No contradiction with annotations.

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

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

Four sentences, front-loaded with the core purpose, then input modes, cost/auth, and the key semantic caveat. Every sentence adds operational value with no filler or repetition.

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

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

With no output schema, the description still tells the agent what the tool returns: which values appear in the source, which do not, and a supporting excerpt for each. Combined with the fully detailed input schema, an agent has enough to invoke this tool correctly.

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

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

Schema description coverage is 100% and each parameter already has a meaningful description, including max lengths and baseUrl's 'never fetched' behavior. The description adds general context like 'url (or raw html/text)' and field-by-field checking, but not significant new parameter-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb ('Check') and resource ('data you already have' against 'the page it claims to come from'), with a precise method ('field by field'). This clearly distinguishes it from sibling extraction/read tools by focusing on verification rather than retrieval or extraction.

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

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

It implies when to use the tool ('data you already have') and gives a clear scope limitation: it answers 'is this value present in this page', NOT 'does the page say this about that'. It does not explicitly name alternative sibling tools, but the boundary around intended use 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?

Goes far beyond the annotations: discloses per-run credit charges (1/3/8/15 plus 2 when rendered), hourly-run cost implications, plan caps on active monitors, schedule slippage, webhook POST with X-Contrie-Signature and one-time secret return, and history recording of before/after with evidence status and field diff. The non-idempotency warning is consistent with idempotentHint=false, so no contradiction.

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

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

Purpose is front-loaded in the first sentence and every subsequent sentence carries substantive information (billing, schedule, webhook, caps, auth, idempotency). It is dense and somewhat run-on, but there is little dead weight to cut.

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 5-parameter, non-idempotent, authenticated, metered creation tool with no output schema, the description covers auth method (OAuth or API key header), cost model, limits, side effects, webhook signing, and retry hazard — everything an agent needs to invoke it safely.

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 url, every, schema, extract, and webhookUrl. The description only restates the 'every' minimum and slot-delay behavior rather than adding new semantics for any parameter, 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?

States a specific verb and resource with scope: 'Watch one public web page for one question and be told when the answer changes.' The 'one page / one question' framing plus the baseline-then-schedule mechanic clearly separates it from contrie_monitors (listing), contrie_unwatch (removal), and contrie_extract (one-off).

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 operating context — creation is not idempotent and the agent should list existing monitors before retrying a lost response — which implicitly routes to the contrie_monitors sibling. It lacks explicit when-not-to-use or alternative-selection guidance (e.g., when to prefer contrie_extract over monitoring).

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