softwiro-templates

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

Goes well beyond the annotations: it states the workbook is ephemeral ("Nothing is saved on the server"), explains the idempotency nuance the idempotentHint cannot express — same input, same output, except templates using TODAY() follow server date — and discloses concrete limits (500 rows, 500 cells, 15 seconds) plus failure messages naming the bad sheet, column, cell, or template id. It also warns that formula cells in `cells` are ignored and surfaced in warnings, which is behavior no annotation or schema field conveys.

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

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

It is front-loaded and the parameter walkthrough is easy to scan, but the core claim is stated twice — "Fills a template ... recalculates ... returns the results" is re-said as "Sends your records into the template and returns what its own formulas calculate" — and "Nothing is saved on the server" is repeated as "Nothing is stored." Those duplicated sentences cost space that could have gone to sibling differentiation.

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

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

With no output schema, the description carries the return contract itself and does so: it names the summary cells from the schema plus calculated columns for every submitted row, and explains how `read` narrows the response. For a 5-parameter tool with nested objects, limits, error modes, and idempotency caveats all covered, nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the date format "YYYY-MM-DD" is not in the schema, the mode default of "replace" is restated with its clearing consequence, and it clarifies that only typed/input columns should be filled while calculated columns come back in rows[].calculated. It stops short of exhaustively documenting every field, but it more than compensates for a schema that already does most of the work.

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

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

The opening sentence names a specific verb chain (fills, recalculates, returns) and the exact resource (a template plus its own formulas), so an agent knows precisely what the call produces. It does not, however, distinguish itself from the sibling run_calculator, which sounds like it could do something similar — the only sibling it names is get_schema, and only as a prerequisite.

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?

"Call get_schema first" gives an explicit prerequisite, and the mode/read defaults tell the agent what happens when options are omitted. There is no guidance on when to prefer this over run_calculator or list_calculators, so the routing decision against the closest-sounding 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 cover read-only, idempotent, non-destructive, closed-world behavior, so the description does not need to repeat safety. It adds genuinely new context: the xlsx link requires no sign-in, the online link points to the template page where the sheet can be filled in-browser, and the failure mode ("unknown template id") when the id did not originate from list_templates. Not fully 5 since return shape details (link format, expiration) are not touched.

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 output is front-loaded in the first sentence, followed by usage rule and error case. The nested parentheticals with extra detail ("the free Excel file to download, no sign-in") are informative but make the sentence dense; still, no sentence is disposable.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers what is returned, what each element means, when to prefer it, and the failure condition. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter already documents its provenance and gives an example id. The description largely echoes that provenance and only adds the error behavior for an invalid id, so it adds marginal meaning beyond the schema. 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?

The description states a specific verb and resource ("Returns two links for one template") and immediately enumerates what each link is (xlsx free Excel file, online browser-fill page). It is clearly distinguishable from siblings such as calculate and list_templates 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?

It gives an explicit selection rule ("Use it when the user wants the file itself to keep and edit") and names the competing tool with the reason to avoid it ("because calculate saves nothing"). It also states the precondition that the id must come from list_templates, which is a when-to-use constraint in itself.

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 and the description's "Read-only" is redundant. What the description does add beyond annotations is the disclosed error mode ("unknown template id") tied to a precondition, which helps the agent anticipate failure and recover via list_templates.

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 payload of what is returned, then sequencing, then caveats. The only waste is the standalone "Read-only" sentence, which merely repeats readOnlyHint=true, and the long enumeration is dense but each item is informative.

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 full burden of explaining return values, and it does so thoroughly (sheets, tables, column roles, examples, dropdowns, settings and result cells). Combined with the sequencing guidance and error condition, an agent has everything needed to call it correctly.

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

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

Only one parameter and schema description coverage is 100%, with the schema already stating "Template id from list_templates, for example gym-memberships." The description restates the same constraint (id must come from list_templates) without adding format, casing, or example detail beyond the schema, so the 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?

States a specific verb and resource ("Returns the structure of one template") and then enumerates what that structure contains: sheets, record tables with header/first/last row and capacity, input vs formula columns, examples, dropdowns, settings cells, result cells. This is far more precise than any sibling name suggests, so an agent can distinguish it from list_templates and calculate 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?

Explicitly prescribes a position in the workflow: "Call it after list_templates and before calculate," and explains the reason (use exact sheet/column names, fill only input columns). It also names the failure condition (id not from list_templates), which effectively excludes passing arbitrary ids.

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 carried by structured data. The description adds real context beyond that: it discloses the catalog composition, that input names are returned, and that nothing is stored. The "Read-only" clause partly repeats the annotation, which keeps this just below a 5.

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

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

The scoping statement and the catalog are front-loaded, and every later sentence (one-off use, run_calculator next, list_templates alternative, read-only) carries distinct information. The parenthetical list of 23 calculators is long but earns its place as the disambiguation payload; it could have been trimmed to group labels without much loss.

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

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

With one optional parameter, no output schema, and annotations covering safety, the description supplies nearly everything an agent needs: what is listed, how to filter, what to do next, and the sibling to avoid. The only gap is the exact response shape (field names per calculator), which is acceptable given the small fixed catalog.

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 query parameter is already well documented with Arabic/English examples and match fields, so the baseline is 3. The description nevertheless adds value by enumerating the 23 calculator names, which effectively tells the agent what search terms will hit (zakat, vat, ovulation, etc.) and that omitting the query returns all 23.

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: "Lists the 23 quick calculators with their input names," and then names the full catalog split into 13 Softwiro and 10 Qintar calculators. This makes it immediately distinguishable from list_templates (multi-row tracking sheets) and from run_calculator (execution). An agent knows exactly what it gets back 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?

It states the selection condition explicitly: use this for a one-off calculation that does not need a spreadsheet, then call run_calculator; use list_templates for multi-row tracking sheets. That is a clear when-to-use plus a named alternative for the adjacent case. The only minor omission is that calculate and get_schema are not mentioned, but the core routing decision is fully covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint: false and openWorldHint: false, so the safety profile is covered. The description still adds useful behavior beyond them: that nothing is stored, and importantly that an empty query returns the entire catalog rather than erroring or returning nothing. It does not discuss result size limits or pagination, which is the remaining gap for a ~70-item catalog.

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 short sentences ordered purpose → return shape → when to use → when not to use → edge case, with the scope front-loaded. The sector enumeration is the only long element, and it earns its place by giving the agent matching vocabulary for queries.

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

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

For a one-optional-parameter, read-only search tool, the definition covers purpose, return fields (compensating for the absent output schema), query semantics, empty-query behavior and the sibling routing decision. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, and the parameter's own description already covers Arabic/English input, which fields are matched, and that omitting it lists everything. The description restates the same semantics rather than extending them with matching behavior details (e.g. partial vs whole-word matching, multi-word handling), so baseline 3 applies.

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

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

States a specific verb ("Search") and resource ("catalog of about 70 free Arabic Excel templates") with concrete domain examples and the exact fields returned (id, Arabic title, description, sector, page URL, download URL). It explicitly contrasts itself with the sibling list_calculators, so an agent can pick it 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?

Gives an explicit positive trigger ("use it first whenever the user needs a tracking sheet or a multi-row calculation") and an explicit exclusion that names the alternative tool and the cases that select it ("For a single quick calculation (VAT, BMI, gold zakat) use list_calculators instead"). Nothing about when to invoke it 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 readOnly, idempotent, openWorld and non-destructive, yet the description still adds substantial context: nothing is persisted, gold calculators fetch live prices and report a price date, prices-unavailable yields an error rather than a guess, and invalid inputs fail with a message naming the field. It also flags that results are indicative and not a fatwa or medical advice, which the agent needs to relay.

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 action and return format are front-loaded in the first sentence, and the subsequent sentences each carry distinct information (persistence, live-price behavior, validation errors, disclaimers). It is slightly long but no sentence is 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?

With no output schema and a nested free-form inputs object, the description does a good job explaining what comes back (JSON matching the website's numbers) and how failures surface. The one remaining gap is that the per-calculator input names live entirely in list_calculators output rather than here, though the description points there explicitly.

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 id and inputs are already documented including the YYYY-MM-DD and EGP-per-gram conventions. The description only reinforces that id comes from list_calculators and that failures name the offending field, adding little beyond the schema; the 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 first sentence gives a specific verb and resource ("Runs one calculator from list_calculators and returns its result as JSON") and ties the tool to the discovery sibling list_calculators. It does not, however, distinguish itself from the sibling tool named calculate, which an agent would reasonably see as overlapping.

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 implied through the prerequisite that the id must come from list_calculators, which gives the agent a workflow. There is no explicit when-to-use or when-not-to-use guidance, and nothing explains how this differs from the calculate sibling, so the agent must infer the choice.

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